feat: changelog sorting options (#165)

* minor: add option for sorting changelog entries by semantic version

Signed-off-by: gardar <gardar@users.noreply.github.com>

* feat: allow more granular control of changelog sorting

Signed-off-by: gardar <gardar@users.noreply.github.com>

* fix: lint

Signed-off-by: gardar <gardar@users.noreply.github.com>

* fix: apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* fix: rename reverse version sorting key as suggested

Signed-off-by: gardar <gardar@users.noreply.github.com>

---------

Signed-off-by: gardar <gardar@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

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_sort: alphanumerical

changelogs/fragments/165-changelog-sort-option.yml

@@ -0,0 +1,6 @@
+---
+minor_changes:
+  - >
+    Adds a new configuration option ``changelog_sort``.
+    This option allows sorting of changelog entries in ``changelogs/changelog.yaml``
+    (https://github.com/ansible-community/antsibull-changelog/pull/165).

docs/changelog-configuration.md

@@ -98,6 +98,17 @@ 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_sort` (string)
+
+The default is `alphanumerical`.
+
+This option controls the sorting of changelog entries in `changelogs/changelog.yaml`. It accepts the following values:
+
+- `unsorted`: No sorting is performed on the changelog entries. The entries are stored in the order they were added.
+- `version`: Sorts the changelog entries by version in ascending order.
+- `version_reversed`: Sorts the changelog entries by version in descending order.
+- `alphanumerical`: Sorts the changelog entries in alphanumerical order.
+
 ### `flatmap` (optional boolean)
 
 The default value is `null`.

src/antsibull_changelog/changes.py

@@ -151,7 +151,13 @@ def save(self) -> None:
         """
         self.sort()
         self.data["ancestor"] = self.ancestor
-        store_yaml(self.path, self.data, self.config.changelog_nice_yaml)
+        sort_keys = self.config.changelog_sort == "alphanumerical"
+        store_yaml(
+            self.path,
+            self.data,
+            nice=self.config.changelog_nice_yaml,
+            sort_keys=sort_keys,
+        )
 
     def add_release(
         self,
@@ -507,6 +513,16 @@ def sort(self) -> None:
         """
         Sort change metadata in place.
         """
+        if self.config.changelog_sort in ["version", "version_reversed"]:
+            reverse_order = self.config.changelog_sort == "version_reversed"
+            self.data["releases"] = dict(
+                sorted(
+                    self.data["releases"].items(),
+                    key=lambda t: self.version_constructor(t[0]),
+                    reverse=reverse_order,
+                )
+            )
+
         for _, config in self.data["releases"].items():
             if "modules" in config:
                 config["modules"] = sorted(

src/antsibull_changelog/config.py

@@ -380,6 +380,7 @@ class ChangelogConfig:
     output_formats: set[TextFormat]
     add_plugin_period: bool
     changelog_nice_yaml: bool
+    changelog_sort: str
 
     def __init__(
         self,
@@ -467,6 +468,8 @@ def __init__(
 
         self.changelog_nice_yaml = self.config.get("changelog_nice_yaml", False)
 
+        self.changelog_sort = self.config.get("changelog_sort", "alphanumerical")
+
         self._validate_config(ignore_is_other_project)
 
     def _validate_config(self, ignore_is_other_project: bool) -> None:
@@ -485,6 +488,17 @@ def _validate_config(self, ignore_is_other_project: bool) -> None:
         if self.changes_format != "combined":
             raise ChangelogError('changes_format must be "combined"')
 
+        valid_sort_options = [
+            "unsorted",
+            "version",
+            "version_reversed",
+            "alphanumerical",
+        ]
+        if self.changelog_sort not in valid_sort_options:
+            raise ChangelogError(
+                f"Invalid changelog_sort option: {self.changelog_sort}"
+            )
+
     def store(self) -> None:  # noqa: C901
         """
         Store changelog configuration file to disk.
@@ -506,6 +520,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_sort": self.changelog_sort,
         }
         if not self.is_collection:
             if self.use_semantic_versioning:
@@ -585,6 +600,7 @@ def default(
             "sanitize_changelog": True,
             "add_plugin_period": True,
             "changelog_nice_yaml": False,
+            "changelog_sort": "alphanumerical",
         }
         if title is not None:
             config["title"] = title

src/antsibull_changelog/yaml.py

@@ -42,7 +42,9 @@ 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_keys: bool = True
+) -> None:
     """
     Store ``content`` as YAML file under ``path``.
     """
@@ -53,4 +55,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=sort_keys,
         )