Add ability to provide changelog for add-ons

_validate/addonManifest.py

@@ -31,6 +31,9 @@ class AddonManifest(ConfigObj):
 		# Long description with further information and instructions
 		description = string(default=None)
 
+		# Document changes between the previous and the current versions.
+		changelog = string(default=None)
+
 		# Name of the author or entity that created the add-on
 		author = string()
 
@@ -89,8 +92,8 @@ def __init__(self, input: str | TextIOBase, translatedInput: str | None = None):
 		self._translatedConfig = None
 		if translatedInput is not None:
 			self._translatedConfig = ConfigObj(translatedInput, encoding="utf-8", default_encoding="utf-8")
-			for key in ("summary", "description"):
-				val: str = self._translatedConfig.get(key)  # type: ignore[reportUnknownMemberType]
+			for key in ("summary", "description", "changelog"):
+				val: str | None = self._translatedConfig.get(key)  # type: ignore[reportUnknownMemberType]
 				if val:
 					self[key] = val
 

_validate/addonVersion_schema.json

@@ -28,11 +28,13 @@
 			"sourceURL": "https://github.com/nvaccess/addon-datastore/",
 			"license": "GPL v2",
 			"licenseURL": "https://github.com/nvaccess/addon-datastore/license.MD",
+			"changelog": "New features",
 			"translations": [
 				{
 					"language": "de",
 					"displayName": "Mein Addon",
-					"description": "erleichtert das Durchführen von xyz"
+					"description": "erleichtert das Durchführen von xyz",
+					"changelog": "Neue Funktionen"
 				}
 			],
 			"reviewUrl": "https://github.com/nvaccess/addon-datastore/discussions/1942#discussioncomment-7453248",
@@ -228,6 +230,16 @@
 			"title": "The URL of the license",
 			"type": "string"
 		},
+		"changelog": {
+			"$id": "#/properties/changelog",
+			"default": "",
+			"description": "Changes between the previous and the current version",
+			"examples": [
+				"New feature"
+			],
+			"title": "Add-on changelog (en)",
+			"type": "string"
+		},
 		"legacy": {
 			"$id": "#/properties/legacy",
 			"default": false,
@@ -247,7 +259,8 @@
 					{
 						"language": "de",
 						"displayName": "Mein Addon",
-						"description": "erleichtert das Durchführen von xyz"
+						"description": "erleichtert das Durchführen von xyz",
+						"changelog": "Neue Funktionen"
 					}
 				]
 			],
@@ -357,7 +370,8 @@
 				{
 					"language": "de",
 					"displayName": "Mein Addon",
-					"description": "erleichtert das Durchführen von xyz"
+					"description": "erleichtert das Durchführen von xyz",
+					"changelog": "Neue Funktionen"
 				}
 			],
 			"required": [
@@ -393,6 +407,15 @@
 					],
 					"title": "The translated description",
 					"type": "string"
+				},
+				"changelog": {
+					"default": "",
+					"description": "Translated description of changes between the previous and this add-on version",
+					"examples": [
+						"Neue Funktionen"
+					],
+					"title": "The translated changelog",
+					"type": "string"
 				}
 			}
 		}

_validate/createJson.py

@@ -32,6 +32,7 @@ class AddonData:
 	sourceURL: str
 	license: str
 	homepage: str | None
+	changelog: str | None
 	licenseURL: str | None
 	submissionTime: int
 	translations: list[dict[str, str]]
@@ -120,18 +121,32 @@ def _createDataclassMatchingJsonSchema(
 	# Add optional fields
 	homepage: str | None = manifest.get("url")  # type: ignore[reportUnknownMemberType]
 	if not homepage or homepage == "None":
+		# The config default is None
+		# which is parsed by configobj as a string not a NoneType
 		homepage = None
-
+	changelog: str | None = manifest.get("changelog")  # type: ignore[reportUnknownMemberType]
+	if changelog == "None":
+		# The config default is None
+		# which is parsed by configobj as a string not a NoneType
+		changelog = None
 	translations: list[dict[str, str]] = []
 	for langCode, translatedManifest in getAddonManifestLocalizations(manifest):
+		# Add optional translated changelog.
+		translatedChangelog: str | None = translatedManifest.get("changelog")  # type: ignore[reportUnknownMemberType]
+		if translatedChangelog == "None":
+			# The config default is None
+			# which is parsed by configobj as a string not a NoneType
+			translatedChangelog = None
+
 		try:
-			translations.append(
-				{
-					"language": langCode,
-					"displayName": cast(str, translatedManifest["summary"]),
-					"description": cast(str, translatedManifest["description"]),
-				},
-			)
+			translation: dict[str, str] = {
+				"language": langCode,
+				"displayName": cast(str, translatedManifest["summary"]),
+				"description": cast(str, translatedManifest["description"]),
+			}
+			if translatedChangelog is not None:
+				translation["changelog"] = translatedChangelog
+			translations.append(translation)
 		except KeyError as e:
 			raise KeyError(f"Translation for {langCode} missing required key '{e.args[0]}'.") from e
 
@@ -152,6 +167,7 @@ def _createDataclassMatchingJsonSchema(
 		sourceURL=sourceUrl,
 		license=licenseName,
 		homepage=homepage,
+		changelog=changelog,
 		licenseURL=licenseUrl,
 		submissionTime=getCurrentTime(),
 		translations=translations,

_validate/regenerateTranslations.py

@@ -6,6 +6,7 @@
 import glob
 import json
 from urllib.request import urlretrieve
+from typing import cast
 
 from .manifestLoader import getAddonManifest, getAddonManifestLocalizations
 
@@ -23,15 +24,25 @@ def regenerateJsonFile(filePath: str, errorFilePath: str | None) -> None:
 			with open(errorFilePath, "w") as errorFile:
 				errorFile.write(f"Validation Errors:\n{manifest.errors}")
 		return
-
+	changelog = manifest.get("changelog")  # type: ignore[reportUnknownMemberType]
+	if changelog == "None":
+		# The config default is None
+		# which is parsed by configobj as a string not a NoneType
+		changelog = None
 	for langCode, manifest in getAddonManifestLocalizations(manifest):
-		addonData["translations"].append(
-			{
-				"language": langCode,
-				"displayName": manifest["summary"],
-				"description": manifest["description"],
-			},
-		)
+		translatedChangelog: str | None = manifest.get("changelog")  # type: ignore[reportUnknownMemberType]
+		if translatedChangelog == "None":
+			# The config default is None
+			# which is parsed by configobj as a string not a NoneType
+			translatedChangelog = None
+		translation: dict[str, str] = {
+			"language": langCode,
+			"displayName": cast(str, manifest["summary"]),
+			"description": cast(str, manifest["description"]),
+		}
+		if translatedChangelog is not None:
+			translation["changelog"] = translatedChangelog
+		addonData["translations"].append(translation)
 
 	with open(filePath, "wt", encoding="utf-8") as f:
 		json.dump(addonData, f, indent="\t", ensure_ascii=False)

_validate/validate.py

@@ -134,6 +134,19 @@ def checkDescriptionMatches(manifest: AddonManifest, submission: JsonObjT) -> Va
 		)
 
 
+def checkChangelogMatches(manifest: AddonManifest, submission: JsonObjT) -> ValidationErrorGenerator:
+	"""The submission changelog must match the *.nvda-addon manifest changelog field."""
+	changelog = manifest.get("changelog")  # type: ignore[reportUnknownMemberType]
+	if changelog == "None":
+		# The config default is None which is parsed by configobj as a string not a NoneType
+		changelog = None
+	if changelog != submission.get("changelog"):
+		yield (
+			f"Submission 'changelog' must be set to '{changelog}' "
+			f"in json file instead of {submission.get('changelog')}"
+		)
+
+
 def checkUrlMatchesHomepage(manifest: AddonManifest, submission: JsonObjT) -> ValidationErrorGenerator:
 	"""The submission homepage must match the *.nvda-addon manifest url field."""
 	manifestUrl = manifest.get("url")  # type: ignore[reportUnknownMemberType]
@@ -332,6 +345,7 @@ def validateSubmission(submissionFilePath: str, verFilename: str) -> ValidationE
 		manifest = getAddonManifest(addonDestPath)
 		yield from checkSummaryMatchesDisplayName(manifest, submissionData)
 		yield from checkDescriptionMatches(manifest, submissionData)
+		yield from checkChangelogMatches(manifest, submissionData)
 		yield from checkUrlMatchesHomepage(manifest, submissionData)
 		yield from checkAddonId(manifest, submissionFilePath, submissionData)
 		yield from checkMinNVDAVersionMatches(manifest, submissionData)

pyproject.toml

@@ -67,7 +67,6 @@ reportMissingTypeStubs = false
 
 [tool.uv]
 default-groups = "all"
-python-preference = "only-system"
 environments = ["sys_platform == 'win32'"]
 required-version = ">=0.8"
 

tests/testData/addons/fake/13.0.0.json

@@ -8,6 +8,7 @@
 	},
 	"displayName": "mock addon",
 	"description": "The description for the addon",
+	"changelog": "Changes for this add-on version",
 	"homepage": "https://nvaccess.org",
 	"publisher": "Name of addon author or organisation",
 	"minNVDAVersion": {
@@ -23,7 +24,7 @@
 	"channel": "stable",
 	"URL": "https://github.com/nvaccess/dont/use/this/address/fake.nvda-addon",
 	"sha256-comment": "SHA for the fake.nvda-addon file",
-	"sha256": "e27fa778cb99f83ececeb0bc089033929eab5a2fa475ce63e68f50b03b6ab585",
+	"sha256": "50a8011a807665bcb8fdd177c276fef3b3f7f754796c5990ebe14e80c28b14ef",
 	"sourceURL": "https://github.com/nvaccess/dont/use/this/address",
 	"license": "GPL v2",
 	"licenseURL": "https://www.gnu.org/licenses/gpl-2.0.html",

tests/testData/manifest.ini

@@ -1,6 +1,7 @@
 name = fake
 summary = "mock addon"
 description = """The description for the addon"""
+changelog = """Changes for this add-on version"""
 author = "Name of addon author or organisation"
 url = https://nvaccess.org
 version = 13.0

tests/test_createJson.py

@@ -99,6 +99,7 @@ def test_validVersion(self):
 				sourceURL="https://example.com",
 				license="GPL v2",
 				homepage="https://example.com",
+				changelog="""Changes for this add-on version""",
 				licenseURL="https://www.gnu.org/licenses/gpl-2.0.html",
 				submissionTime=createJson.getCurrentTime(),
 				translations=[],

tests/test_validate.py

@@ -89,7 +89,7 @@ def test_missingHTTPsAndExt(self):
 class Validate_checkSha256(unittest.TestCase):
 	"""Tests for the checkSha256 function"""
 
-	validSha = "e27fa778cb99f83ececeb0bc089033929eab5a2fa475ce63e68f50b03b6ab585"
+	validSha = "50a8011a807665bcb8fdd177c276fef3b3f7f754796c5990ebe14e80c28b14ef"
 
 	def test_valid(self):
 		errors = validate.checkSha256(ADDON_PACKAGE, expectedSha=self.validSha.upper())
@@ -152,6 +152,32 @@ def test_invalid(self):
 		)
 
 
+class Validate_checkChangelogMatches(unittest.TestCase):
+	def setUp(self):
+		self.submissionData = getValidAddonSubmission()
+		self.manifest = getAddonManifest()
+
+	def test_valid(self):
+		errors = list(
+			validate.checkChangelogMatches(self.manifest, self.submissionData),
+		)
+		self.assertEqual(errors, [])
+
+	def test_invalid(self):
+		badChangelog = "bad changelog"
+		self.submissionData["changelog"] = badChangelog
+		errors = list(
+			validate.checkChangelogMatches(self.manifest, self.submissionData),
+		)
+		self.assertEqual(
+			errors,
+			[
+				f"Submission 'changelog' must be set to '{self.manifest['changelog']}' in json file"
+				f" instead of {badChangelog}",
+			],
+		)
+
+
 class Validate_checkAddonId(unittest.TestCase):
 	"""
 	Manifest 'name' considered source of truth for addonID