Add build data reformatting tool; improve changelog.yaml YAML represe…

…ntation; add changelog.yaml linter (#638)

* Add reformatting tool.

* Adjust Ansible changelog config for nicer and easier readable changelog.yaml.

* Fix comment.

* Add changelog.yaml linting step to lint-build-data.

* Lint.

* Use strict linting.

Ref: ansible-community/antsibull-changelog#182

* Depend on antsibull-changelog 0.31.0+.

* Fix docstrings.

.github/workflows/antsibull-build.yml

@@ -28,10 +28,10 @@ jobs:
           - name: Ansible 8
             options: '-e antsibull_ansible_version=8.99.0'
             python: '3.9'
-            antsibull_changelog_ref: 0.24.0
+            antsibull_changelog_ref: 0.31.0
             antsibull_core_ref: main
             antsibull_docs_parser_ref: 1.1.0
-            antsibull_docutils_ref: 1.0.0  # isn't used by antsibull-changelog 0.24.0
+            antsibull_docutils_ref: 1.0.0
             antsibull_fileutils_ref: main
           - name: Ansible 9
             options: '-e antsibull_ansible_version=9.99.0'

changelogs/fragments/638-reformat.yml

@@ -0,0 +1,5 @@
+minor_changes:
+  - "Add a subcommand ``reformat-build-data`` which reformats the changelog.yaml file (https://github.com/ansible-community/antsibull-build/pull/638)."
+  - "Adjust the changelog config so that changelog.yaml has a nicer order and nicer layout (https://github.com/ansible-community/antsibull-build/pull/638)."
+  - "Add changelog.yaml linting to ``lint-build-data`` (https://github.com/ansible-community/antsibull-build/pull/638)."
+  - "Now depends on antsibull-changelog >= 0.31.0 (https://github.com/ansible-community/antsibull-build/pull/638)."

pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
 ]
 requires-python = ">=3.9"
 dependencies = [
-    "antsibull-changelog >= 0.24.0",
+    "antsibull-changelog >= 0.31.0",
     "antsibull-core >= 3.1.0, < 4.0.0",
     "antsibull-docs-parser >= 1.1.0, < 2.0.0",
     "antsibull-fileutils >= 1.0.0, < 2.0.0",

src/antsibull_build/build_ansible_commands.py

@@ -500,7 +500,7 @@ def prepare_command() -> int:
         f"`Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`_",
         overwrite_release_summary=False,
     )
-    ansible_changelog.changes.save()
+    ansible_changelog.save()
 
     # Write dependency file
     deps_file.write(

src/antsibull_build/build_data_lint.py

@@ -5,13 +5,14 @@
 # SPDX-FileCopyrightText: Ansible Project, 2024
 
 """
-Classes to lint collection-meta.yaml
+Code to lint build data.
 """
 
 from __future__ import annotations
 
 import os
 
+from antsibull_changelog.lint import lint_changelog_yaml as _lint_changelog_yaml
 from antsibull_core import app_context
 from antsibull_core.collection_meta import lint_collection_meta as _lint_collection_meta
 from antsibull_core.dependency_files import parse_pieces_file
@@ -34,8 +35,15 @@ def lint_build_data() -> int:
         all_collections=all_collections,
     )
 
+    # Lint changelog.yaml
+    changelog_path = os.path.join(data_dir, "changelog.yaml")
+    for path, _, __, message in _lint_changelog_yaml(
+        changelog_path, no_semantic_versioning=True, strict=True
+    ):
+        errors.append(f"{path}: {message}")
+
     # Show results
-    for message in errors:
+    for message in sorted(errors):
         print(message)
 
     return 3 if errors else 0

src/antsibull_build/build_data_reformat.py

@@ -0,0 +1,28 @@
+# Author: Felix Fontein <[email protected]>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
+# https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: Ansible Project, 2024
+
+"""
+Code to reformat build data.
+"""
+
+from __future__ import annotations
+
+from antsibull_core import app_context
+
+from .changelog import ChangelogData
+
+
+def reformat_build_data() -> int:
+    """Reformat build data."""
+    app_ctx = app_context.app_ctx.get()
+
+    data_dir: str = app_ctx.extra["data_dir"]
+
+    # Reformat changelog.yaml
+    changelog = ChangelogData.ansible(directory=data_dir)
+    changelog.save()
+
+    return 0

src/antsibull_build/changelog.py

@@ -107,7 +107,9 @@ def ansible(
         paths = PathsConfig.force_ansible("")
 
         config = ChangelogConfig.default(paths, CollectionDetails(paths), "Ansible")
-        # TODO: adjust the following lines once Ansible switches to semantic versioning
+        config.changelog_nice_yaml = True
+        config.changelog_sort = "version"
+        # While Ansible uses semantic versioning, the version numbers must be PyPI compatible
         config.use_semantic_versioning = False
         config.release_tag_re = r"""(v(?:[\d.ab\-]|rc)+)"""
         config.pre_release_tag_re = r"""(?P<pre_release>(?:[ab]|rc)+\d*)$"""
@@ -156,6 +158,9 @@ def add_ansible_release(
         ):
             release_date["changes"]["release_summary"] = release_summary
 
+    def save(self):
+        self.changes.save()
+
 
 def read_file(tarball_path: str, matcher: t.Callable[[str], bool]) -> bytes | None:
     with tarfile.open(tarball_path, "r:gz") as tar:

src/antsibull_build/cli/antsibull_build.py

@@ -55,6 +55,7 @@
 )
 from ..build_changelog import build_changelog  # noqa: E402
 from ..build_data_lint import lint_build_data  # noqa: E402
+from ..build_data_reformat import reformat_build_data  # noqa: E402
 from ..constants import MINIMUM_ANSIBLE_VERSION, SANITY_TESTS_DEFAULT  # noqa: E402
 from ..dep_closure import validate_dependencies_command  # noqa: E402
 from ..from_source import verify_upstream_command  # noqa: E402
@@ -86,6 +87,7 @@
     "announcements": announcements_command,
     "send-announcements": send_announcements_command,
     "lint-build-data": lint_build_data,
+    "reformat-build-data": reformat_build_data,
 }
 DISABLE_VERIFY_UPSTREAMS_IGNORES_SENTINEL = "NONE"
 DEFAULT_ANNOUNCEMENTS_DIR = Path("build/announce")
@@ -106,6 +108,7 @@ def _normalize_build_options(args: argparse.Namespace) -> None:
         "verify-upstreams",
         "sanity-tests",
         "send-announcements",
+        "reformat-build-data",
     ):
         return
 
@@ -807,6 +810,16 @@ def parse_args(program_name: str, args: list[str]) -> argparse.Namespace:
         f" {DEFAULT_PIECES_FILE}",
     )
 
+    reformat_build_data_parser = subparsers.add_parser(
+        "reformat-build-data",
+        description="Reformat some of the build data, like the changelog.yaml."
+        " Should be done after manual edits to avoid surprising reformattings"
+        " later on.",
+    )
+    reformat_build_data_parser.add_argument(
+        "--data-dir", default=".", help="Directory to read .build and .deps files from"
+    )
+
     # This must come after all parser setup
     if HAS_ARGCOMPLETE:
         argcomplete.autocomplete(parser)