Add deterministic sorting to versioned changes file

Author: ArBridgeman

exasol/toolbox/util/release/changelog.py

@@ -2,7 +2,6 @@
 
 from datetime import datetime
 from inspect import cleandoc
-from itertools import chain
 from pathlib import Path
 
 from exasol.toolbox.util.dependencies.poetry_dependencies import (
@@ -75,16 +74,12 @@ def _describe_dependency_changes(self) -> str:
         )
 
         changes_by_group: list[str] = []
-        # preserve order of keys from old group
-        groups = list(
-            dict.fromkeys(
-                chain(
-                    previous_dependencies_in_groups.keys(),
-                    current_dependencies_in_groups.keys(),
-                )
-            )
+        # dict.keys() returns a set
+        all_groups = (
+            previous_dependencies_in_groups.keys()
+            | current_dependencies_in_groups.keys()
         )
-        for group in groups:
+        for group in self._sort_groups(all_groups):
             previous_dependencies = previous_dependencies_in_groups.get(group, {})
             current_dependencies = current_dependencies_in_groups.get(group, {})
             changes = DependencyChanges(
@@ -96,6 +91,21 @@ def _describe_dependency_changes(self) -> str:
                 changes_by_group.append(f"\n### `{group}`\n{changes_str}\n")
         return "".join(changes_by_group)
 
+    @staticmethod
+    def _sort_groups(groups: set[str]) -> list[str]:
+        """
+        Prepare a deterministic sorting for groups shown in the versioned changes file:
+            - `main` group should always be first
+            - remaining groups are sorted alphabetically
+        """
+        main = "main"
+        if main not in groups:
+            # sorted converts set to list
+            return sorted(groups)
+        remaining_groups = groups - {main}
+        # sorted converts set to list
+        return [main] + sorted(remaining_groups)
+
     def _update_changelog_table_of_contents(self) -> None:
         """
         Read in existing `changelog.md` and append to appropriate sections

test/unit/util/release/changelog_test.py

@@ -143,6 +143,22 @@ def test_describe_dependency_changes(changelogs, mock_dependencies):
             "* Added dependency `package2:0.2.0`\n"
         )
 
+    @staticmethod
+    @pytest.mark.parametrize(
+        "groups,expected",
+        [
+            pytest.param(
+                {"dev", "abcd", "main"}, ["main", "abcd", "dev"], id="with_main"
+            ),
+            pytest.param(
+                {"dev", "abcd", "bacd"}, ["abcd", "bacd", "dev"], id="without_main"
+            ),
+        ],
+    )
+    def test_sort_groups(changelogs, groups, expected):
+        result = changelogs._sort_groups(groups)
+        assert result == expected
+
     @staticmethod
     def test_update_changelog_table_of_contents(changelogs, changes_md):
         changelogs._update_changelog_table_of_contents()