feat: changelog sorting options

changelogs/config.yaml

@@ -15,26 +15,27 @@ notesdir: fragments
 prelude_section_name: release_summary
 prelude_section_title: Release Summary
 sections:
-- - major_changes
-  - Major Changes
-- - minor_changes
-  - Minor Changes
-- - breaking_changes
-  - Breaking Changes / Porting Guide
-- - deprecated_features
-  - Deprecated Features
-- - removed_features
-  - Removed Features (previously deprecated)
-- - security_fixes
-  - Security Fixes
-- - bugfixes
-  - Bugfixes
-- - known_issues
-  - Known Issues
+  - - major_changes
+    - Major Changes
+  - - minor_changes
+    - Minor Changes
+  - - breaking_changes
+    - Breaking Changes / Porting Guide
+  - - deprecated_features
+    - Deprecated Features
+  - - removed_features
+    - Removed Features (previously deprecated)
+  - - security_fixes
+    - Security Fixes
+  - - bugfixes
+    - Bugfixes
+  - - known_issues
+    - Known Issues
 use_semantic_versioning: true
 title: Ansible Changelog Tool
 output_formats:
   - rst
   - md
 add_plugin_period: false
-changelog_nice_yaml: false
+changelog_nice_yaml: false
+changelog_semantic_versioning_sort: false

docs/changelog-configuration.md

@@ -103,6 +103,13 @@ YAML encoding that is compatible with ansible-lint's default rules.
     The exact format used might be adjusted in the future if new releases of ansible-lint
     adjust their yamllint configuration.
 
+### `changelog_semantic_versioning_sort` (boolean)
+
+The default is `false`.
+
+When set to `true` the changelog entries in `changelogs/changelog.yaml` entries will
+be sorted by semantic version.
+
 ### `flatmap` (optional boolean)
 
 The default value is `null`.

src/antsibull_changelog/changes.py

@@ -156,7 +156,12 @@ def save(self) -> None:
         """
         self.sort()
         self.data["ancestor"] = self.ancestor
-        store_yaml(self.path, self.data, self.config.changelog_nice_yaml)
+        store_yaml(
+            self.path,
+            self.data,
+            self.config.changelog_nice_yaml,
+            self.config.changelog_semantic_versioning_sort,
+        )
 
     def add_release(
         self,
@@ -416,7 +421,17 @@ def update_fragments(
     def sort(self) -> None:
         """
         Sort change metadata in place.
-        """
+        Optionally sorts by semantic version.
+        """
+        if self.config.changelog_semantic_versioning_sort:
+            self.data["releases"] = dict(
+                sorted(
+                    self.data["releases"].items(),
+                    key=lambda t: [int(v) for v in t[0].split(".")],
+                    reverse=True,
+                ),
+            )
+
         for _, config in self.data["releases"].items():
             if "modules" in config:
                 config["modules"] = sorted(config["modules"])

src/antsibull_changelog/config.py

@@ -380,6 +380,7 @@ class ChangelogConfig:
     output_formats: set[TextFormat]
     add_plugin_period: bool
     changelog_nice_yaml: bool
+    changelog_semantic_versioning_sort: bool
 
     def __init__(
         self,
@@ -471,6 +472,10 @@ def __init__(
 
         self.changelog_nice_yaml = self.config.get("changelog_nice_yaml", False)
 
+        self.changelog_semantic_versioning_sort = self.config.get(
+            "changelog_semantic_versioning_sort", False
+        )
+
         self._validate_config(ignore_is_other_project)
 
     def _validate_config(self, ignore_is_other_project: bool) -> None:
@@ -522,6 +527,7 @@ def store(self) -> None:  # noqa: C901
             "sanitize_changelog": self.sanitize_changelog,
             "add_plugin_period": self.add_plugin_period,
             "changelog_nice_yaml": self.changelog_nice_yaml,
+            "changelog_semantic_versioning_sort": self.changelog_semantic_versioning_sort,
         }
         if not self.is_collection:
             if self.use_semantic_versioning:
@@ -602,6 +608,7 @@ def default(
             "sanitize_changelog": True,
             "add_plugin_period": True,
             "changelog_nice_yaml": False,
+            "changelog_semantic_versioning_sort": False,
         }
         if title is not None:
             config["title"] = title

src/antsibull_changelog/yaml.py

@@ -42,7 +42,7 @@ def load_yaml(path: str) -> Any:
         return yaml.load(stream, Loader=_SafeLoader)
 
 
-def store_yaml(path: str, content: Any, nice: bool = False) -> None:
+def store_yaml(path: str, content: Any, nice: bool = False, sort: bool = False) -> None:
     """
     Store ``content`` as YAML file under ``path``.
     """
@@ -53,4 +53,5 @@ def store_yaml(path: str, content: Any, nice: bool = False) -> None:
             default_flow_style=False,
             Dumper=_IndentedDumper if nice else _SafeDumper,
             explicit_start=nice,
+            sort_keys=not sort,
         )