Clear release notes and migration script (#351)

We also add some convenience function to the migration template so it is
available for future use.

Author: llucax

.github/cookiecutter-migrate.template.py

@@ -20,6 +20,7 @@
 And remember to follow any manual instructions for each run.
 """  # noqa: E501
 
+import hashlib
 import os
 import subprocess
 import tempfile
@@ -98,6 +99,26 @@ def replace_file_contents_atomically(  # noqa; DOC501
         raise
 
 
+def calculate_file_sha256_skip_lines(filepath: Path, skip_lines: int) -> str | None:
+    """Calculate SHA256 of file contents excluding the first N lines.
+
+    Args:
+        filepath: Path to the file to hash
+        skip_lines: Number of lines to skip at the beginning
+
+    Returns:
+        The SHA256 hex digest, or None if the file doesn't exist
+    """
+    if not filepath.exists():
+        return None
+
+    # Read file and normalize line endings to LF
+    content = filepath.read_text(encoding="utf-8").replace("\r\n", "\n")
+    # Skip first N lines and ensure there's a trailing newline
+    remaining_content = "\n".join(content.splitlines()[skip_lines:]) + "\n"
+    return hashlib.sha256(remaining_content.encode()).hexdigest()
+
+
 def manual_step(message: str) -> None:
     """Print a manual step message in yellow."""
     print(f"\033[0;33m>>> {message}\033[0m")

RELEASE_NOTES.md

@@ -2,16 +2,11 @@
 
 ## Summary
 
-This release introduces a new MkDocs macros *pluglet* system that simplifies documentation setup and provides enhanced functionality for version information and code annotations. It also includes changes to how pytest warnings are handled in templates.
+<!-- Here goes a general summary of what this release is about -->
 
 ## Upgrading
 
-- The `nox` default `pytest` session doesn't pass `-W=all -vv` to `pytest` anymore. You can use the `pyproject.toml` file to configure default options for `pytest`, for example:
-
-    ```toml
-    [tool.pytest.ini_options]
-    addopts = "-W=all -Werror -Wdefault::DeprecationWarning -Wdefault::PendingDeprecationWarning -vv"
-    ```
+<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
 ### Cookiecutter template
 
@@ -23,20 +18,20 @@ curl -sSL https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-
 
 But you might still need to adapt your code:
 
-- `pytest` now uses `-Werror` by default (but still treat deprecations as normal warnings), so if your tests run with warnings, they will now be turned to errors, and you'll need to fix them.
-
-- Projects using `docs/_scripts/macros.py` with customized scripts can use the new provided utility functions. See the [`mkdocstrings_macros` documentation](https://frequenz-floss.github.io/frequenz-repo-config-python/v0.12/reference/frequenz/repo/config/mkdocs/mkdocstrings_macros/) for the new features and setup.
+<!-- Here upgrade steps for cookiecutter specifically -->
 
 ## New Features
 
-- Two new modules were introduced to facilitate the configuration of `macros` for use within docstrings via `mkdocstrings`: [`mkdocstrings_macros`](https://frequenz-floss.github.io/frequenz-repo-config-python/v0.12/reference/frequenz/repo/config/mkdocs/mkdocstrings_macros/) and [`annotations`](https://frequenz-floss.github.io/frequenz-repo-config-python/v0.12/reference/frequenz/repo/config/mkdocs/annotations/).
+<!-- Here goes the main new features and examples or instructions on how to use them -->
 
 ### Cookiecutter template
 
-- `pytest` now uses `-Werror -Wdefault::DeprecationWarning -Wdefault::PendingDeprecationWarning` by default. Deprecations are still treated as warnings, as when testing with the `pytest_min` session is normal to get deprecation warnings as we are using old versions of dependencies.
+<!-- Here new features for cookiecutter specifically -->
 
 ## Bug Fixes
 
+<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+
 ### Cookiecutter template
 
-- Fixed a compatibility issue in the macros doc script with `mkdocsstrings` 0.28.
+<!-- Here bug fixes for cookiecutter specifically -->

cookiecutter/migrate.py

@@ -30,125 +30,8 @@
 
 def main() -> None:
     """Run the migration steps."""
-    add_default_pytest_options()
+    # Add a separation line like this one after each migration step.
     print("=" * 72)
-    migrate_mkdocs_macros()
-    print("=" * 72)
-
-
-def add_default_pytest_options() -> None:
-    """Add default pytest options to pyproject.toml."""
-    pyproject_toml = Path("pyproject.toml")
-    pyproject_toml_content = pyproject_toml.read_text(encoding="utf-8")
-    marker = "[tool.pytest.ini_options]\n"
-    new_options = (
-        "-W=all -Werror -Wdefault::DeprecationWarning "
-        "-Wdefault::PendingDeprecationWarning -vv"
-    )
-
-    print(f"Adding default pytest options to {pyproject_toml}...")
-    if pyproject_toml_content.find(marker) == -1:
-        print(
-            "Couldn't find the the {marker.strip()} marker in pyproject.toml, skipping update."
-        )
-        return
-
-    if pyproject_toml_content.find("\naddopts") >= 0:
-        print("It looks like some options are already configured, skipping update.")
-        manual_step(f"Please consider `{new_options}` if they are not there yet.")
-        return
-
-    replace_file_contents_atomically(
-        pyproject_toml,
-        marker,
-        marker + f'addopts = "{new_options}"\n',
-    )
-
-
-def migrate_mkdocs_macros() -> None:
-    """Migrate from custom macros.py to standard module."""
-    macros_file = Path("docs/_scripts/macros.py")
-    mkdocs_yaml = Path("mkdocs.yaml")
-    if not mkdocs_yaml.exists():
-        mkdocs_yaml = Path("mkdocs.yml")
-
-    known_hashes = {
-        "47a991286132471b6cb666577beb89e78c0f5d4975c53f0dcb319c4338a2c3cb",
-        "6bb960c72b370ac77918f49d7a35f39c0ddb58fe52cf2d12caa2577098fd8469",
-        "7351276ac314955a343bab09d1602e50300887291f841643e9fb79c94acc923c",
-        "8fa5f9f3fd928e17f590e3ab056434474633259d615971404db0d2f3034adb62",
-        "ba3ff5f1612b3dd22372a8ca95394b8ea468f18dcefc494c73811c8433fcb880",
-        "dd32e8759abc43232bb3db5b33c0a7cf8d8442db6135c594968c499d8bae0ce5",
-    }
-
-    print("Checking if docs/_scripts/macros.py can be migrated...")
-
-    file_hash = calculate_file_sha256_skip_lines(macros_file, 2)
-    if not file_hash:
-        return
-
-    if file_hash not in known_hashes:
-        manual_step("The macros.py file seems to be customized. You have two options:")
-        manual_step("")
-        manual_step(
-            "1. Switch to the standard module (if you don't have custom macros):"
-        )
-        manual_step("   a. Update mkdocs.yaml to use the standard module:")
-        manual_step(
-            '      module_name: docs/_scripts/macros -> modules: ["frequenz.repo.config.mkdocs.mkdocstrings_macros"]'  # noqa: E501
-        )
-        manual_step("   b. Remove docs/_scripts/macros.py")
-        manual_step("")
-        manual_step("2. Keep your custom macros but use the standard functionality:")
-        manual_step("   a. Update mkdocs.yaml:")
-        manual_step("      - Keep using module_name: docs/_scripts/macros")
-        manual_step("   b. Update your macros.py to be minimal:")
-        manual_step("      ```python")
-        manual_step(
-            "      from frequenz.repo.config.mkdocs.mkdocstrings_macros import hook_env_with_everything"  # noqa: E501
-        )
-        manual_step("")
-        manual_step("      def define_env(env):")
-        manual_step("          # Add your custom variables, filters, and macros here")
-        manual_step("          env.variables.my_var = 'Example'")
-        manual_step("          env.filters.my_filter = lambda x: x.upper()")
-        manual_step("")
-        manual_step(
-            "          # This must be at the end to enable all standard features"
-        )
-        manual_step("          hook_env_with_everything(env)")
-        manual_step("      ```")
-        manual_step("")
-        manual_step("See the docs for more details:")
-        manual_step(
-            "https://frequenz-floss.github.io/frequenz-repo-config-python/v0.12/reference/frequenz/repo/config/mkdocs/mkdocstrings_macros/"  # noqa: E501
-        )
-        return
-
-    if not mkdocs_yaml.exists():
-        print("mkdocs.yaml/yml not found, skipping macros migration")
-        return
-
-    content = mkdocs_yaml.read_text(encoding="utf-8")
-    if "module_name: docs/_scripts/macros" not in content:
-        print("Custom macros configuration not found in mkdocs.yaml")
-        return
-
-    print("Updating mkdocs.yaml to use standard module...")
-    new_content = content.replace(
-        "module_name: docs/_scripts/macros",
-        'modules: ["frequenz.repo.config.mkdocs.mkdocstrings_macros"]',
-    )
-    new_content = new_content.replace(
-        "# inside docstrings. See the comment in `docs/_scripts/macros.py` for more\n"
-        "  # details\n",
-        "# inside docstrings.\n",
-    )
-
-    replace_file_contents_atomically(mkdocs_yaml, content, new_content)
-
-    print("Removing docs/_scripts/macros.py...")
-    macros_file.unlink()
 
 
 def apply_patch(patch_content: str) -> None:
@@ -216,11 +99,6 @@ def replace_file_contents_atomically(  # noqa; DOC501
         raise
 
 
-def manual_step(message: str) -> None:
-    """Print a manual step message in yellow."""
-    print(f"\033[0;33m>>> {message}\033[0m")
-
-
 def calculate_file_sha256_skip_lines(filepath: Path, skip_lines: int) -> str | None:
     """Calculate SHA256 of file contents excluding the first N lines.
 
@@ -241,5 +119,10 @@ def calculate_file_sha256_skip_lines(filepath: Path, skip_lines: int) -> str | N
     return hashlib.sha256(remaining_content.encode()).hexdigest()
 
 
+def manual_step(message: str) -> None:
+    """Print a manual step message in yellow."""
+    print(f"\033[0;33m>>> {message}\033[0m")
+
+
 if __name__ == "__main__":
     main()