Refactor Changelog modifications so clearer order of operations and have testing

Author: ArBridgeman

exasol/toolbox/nox/_release.py

@@ -13,13 +13,8 @@
     _version,
 )
 from exasol.toolbox.nox.plugin import NoxTasks
-from exasol.toolbox.release import (
-    extract_release_notes,
-    new_changelog,
-    new_changes,
-    new_unreleased,
-)
 from exasol.toolbox.util.git import Git
+from exasol.toolbox.util.release.changelog import Changelogs
 from exasol.toolbox.util.version import (
     ReleaseTypes,
     Version,
@@ -68,22 +63,6 @@ def _update_project_version(session: Session, version: Version) -> Version:
     return version
 
 
-def _update_changelog(version: Version) -> tuple[Path, Path, Path]:
-    unreleased = Path(PROJECT_CONFIG.root) / "doc" / "changes" / "unreleased.md"
-    changelog = Path(PROJECT_CONFIG.root) / "doc" / "changes" / f"changes_{version}.md"
-    changes = Path(PROJECT_CONFIG.root) / "doc" / "changes" / f"changelog.md"
-
-    changelog_content = extract_release_notes(unreleased)
-    changelog.write_text(new_changelog(version, changelog_content))
-
-    unreleased.write_text(new_unreleased())
-
-    changes_content = new_changes(changes, version)
-    changes.write_text(changes_content)
-
-    return changelog, changes, unreleased
-
-
 def _add_files_to_index(session: Session, files: list[Path]) -> None:
     for file in files:
         session.run("git", "add", f"{file}")
@@ -138,7 +117,12 @@ def prepare_release(session: Session) -> None:
         Git.create_and_switch_to_branch(f"release/prepare-{new_version}")
 
     _ = _update_project_version(session, new_version)
-    changelog, changes, unreleased = _update_changelog(new_version)
+
+    changelogs = Changelogs(
+        changes_path=PROJECT_CONFIG.doc / "changes", version=new_version
+    )
+    changelogs.update_changelogs_for_release()
+    changed_files = changelogs.get_changed_files()
 
     pm = NoxTasks.plugin_manager(PROJECT_CONFIG)
     pm.hook.prepare_release_update_version(
@@ -148,18 +132,15 @@ def prepare_release(session: Session) -> None:
     if args.no_add:
         return
 
-    files = [
-        changelog,
-        unreleased,
-        changes,
+    changed_files += [
         PROJECT_CONFIG.root / "pyproject.toml",
         PROJECT_CONFIG.version_file,
     ]
     results = pm.hook.prepare_release_add_files(session=session, config=PROJECT_CONFIG)
-    files += [f for plugin_response in results for f in plugin_response]
+    changed_files += [f for plugin_response in results for f in plugin_response]
     _add_files_to_index(
         session,
-        files,
+        changed_files,
     )
     session.run("git", "commit", "-m", f"Prepare release {new_version}")
 

exasol/toolbox/release/__init__.py

@@ -1,4 +1,4 @@
-import subprocess
+import subprocess  # nosec
 from functools import wraps
 from pathlib import Path
 
@@ -9,7 +9,7 @@ def wrapper(*args, **kwargs) -> str:
         command_list = func(*args, **kwargs).split()
         output = subprocess.run(
             command_list, capture_output=True, text=True, check=True
-        )
+        )  # nosec
         return output.stdout.strip()
 
     return wrapper

exasol/toolbox/util/git.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from datetime import datetime
+from inspect import cleandoc
+from pathlib import Path
+
+from exasol.toolbox.util.version import Version
+
+UNRELEASED_TEXT = "# Unreleased\n"
+
+
+class Changelogs:
+    def __init__(self, changes_path: Path, version: Version) -> None:
+        self.version = version
+        self.unreleased_md: Path = changes_path / "unreleased.md"
+        self.versioned_changelog_md: Path = changes_path / f"changes_{version}.md"
+        self.changes_md: Path = changes_path / "changes.md"
+
+    def _create_new_unreleased(self):
+        """
+        Write a new unreleased changelog file.
+        """
+        self.unreleased_md.write_text(UNRELEASED_TEXT)
+
+    def _create_versioned_changelog(self, content: str) -> None:
+        """
+        Create a changelog entry for a specific version.
+
+        Args:
+            content: The content of the changelog entry.
+
+        """
+        template = cleandoc(
+            f"""
+            # {self.version} - {datetime.today().strftime("%Y-%m-%d")}
+
+            {content}
+            """
+        )
+        self.versioned_changelog_md.write_text(template)
+
+    def _extract_unreleased_notes(self) -> str:
+        """
+        Extract release notes from `unreleased.md`.
+        """
+        with self.unreleased_md.open(mode="r", encoding="utf-8") as f:
+            # skip header when reading in file, as contains # Unreleased
+            lines = f.readlines()[1:]
+        unreleased_content = cleandoc("".join(lines))
+        unreleased_content += "\n"
+        return unreleased_content
+
+    def _update_changelog_table_of_contents(self) -> None:
+        """
+        Read in existing `changelog.md` and append to appropriate sections
+        before writing out to again.
+        """
+        updated_content = []
+        with self.changes_md.open(mode="r", encoding="utf-8") as f:
+            for line in f:
+                updated_content.append(line)
+                if line.startswith("* [unreleased]"):
+                    updated_content.append(
+                        f"* [{self.version}](changes_{self.version}.md)\n"
+                    )
+                if line.startswith("unreleased"):
+                    updated_content.append(f"changes_{self.version}\n")
+        updated_content_str = "".join(updated_content)
+
+        self.changes_md.write_text(updated_content_str)
+
+    def get_changed_files(self) -> list[Path]:
+        return [self.unreleased_md, self.versioned_changelog_md, self.changes_md]
+
+    def update_changelogs_for_release(self) -> None:
+        """
+        Rotates the changelogs as is needed for a release.
+
+          1. Moves the contents of the `unreleased.md` to the `changes_<version>.md`
+          2. Create a new `unreleased.md`
+          3. Updates the table of contents in the `change.md` with the new `changes_<version>.md`
+        """
+
+        # create versioned changelog
+        unreleased_content = self._extract_unreleased_notes()
+        self._create_versioned_changelog(unreleased_content)
+
+        # update other changelogs now that versioned changelog exists
+        self._create_new_unreleased()
+        self._update_changelog_table_of_contents()

exasol/toolbox/util/release/__init__.py

@@ -12,9 +12,8 @@
     ReleaseError,
     _trigger_release,
 )
-from exasol.toolbox.release import (
-    extract_release_notes,
-    new_changelog,
+from exasol.toolbox.util.release.changelog import (
+    _new_changelog,
 )
 from exasol.toolbox.util.version import Version
 
@@ -26,72 +25,30 @@
             Version(0, 1, 0),
             cleandoc(
                 """
-                ## Added
-                * Some great feature
+                    ## Added
+                    * Some great feature
 
-                ## Refactored
-                * Replaced xyz
-                """
+                    ## Refactored
+                    * Replaced xyz
+                    """
             ),
             datetime(2024, 2, 7),
             cleandoc(
                 """
-                # 0.1.0 - 2024-02-07
+                    # 0.1.0 - 2024-02-07
 
-                ## Added
-                * Some great feature
+                    ## Added
+                    * Some great feature
 
-                ## Refactored
-                * Replaced xyz
-                """
+                    ## Refactored
+                    * Replaced xyz
+                    """
             ),
         ),
     ],
 )
 def test_changelog(version, content, date, expected):
-    actual = new_changelog(version, content, date)
-    assert expected == actual
-
-
-@pytest.fixture
-def unreleased_md(tmp_path):
-    file = tmp_path / "unreleased.md"
-    file.write_text(
-        cleandoc(
-            """
-        # Unreleased
-
-        ## ✨ Added
-        * Added Awesome feature
-
-        ## 🔧 Changed
-        * Some behaviour
-
-        ## 🐞 Fixed
-        * Fixed nasty bug
-        """
-        )
-    )
-    yield file
-
-
-def test_extract_release_notes(unreleased_md):
-    expected = (
-        cleandoc(
-            """
-        ## ✨ Added
-        * Added Awesome feature
-
-        ## 🔧 Changed
-        * Some behaviour
-
-        ## 🐞 Fixed
-        * Fixed nasty bug
-        """
-        )
-        + "\n"
-    )
-    actual = extract_release_notes(unreleased_md)
+    actual = _new_changelog(version, content, date)
     assert expected == actual