Port the migration script to Python (#329)

Since this is used to update Python projects, it is safe to assume
Python will be available. Using Python is more portable, so hopefully
the migration script will work more consistently across different OSes.

Also update URL in the migration script to force users to adapt it to
the version they need.

Fixes #302.

Author: llucax

.github/cookiecutter-migrate.template.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Script to migrate existing projects to new versions of the cookiecutter template.
+
+This script migrates existing projects to new versions of the cookiecutter
+template, removing the need to completely regenerate the project from
+scratch.
+
+To run it, the simplest way is to fetch it from GitHub and run it directly:
+
+    curl -sSL https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-python/<tag>/cookiecutter/migrate.py | python3
+
+Make sure to replace the `<tag>` to the version you want to migrate to in the URL.
+
+For jumping multiple versions you should run the script multiple times, once
+for each version.
+
+And remember to follow any manual instructions for each run.
+"""  # noqa: E501
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import SupportsIndex
+
+
+def main() -> None:
+    """Run the migration steps."""
+    # Add a separation line like this one after each migration step.
+    print("=" * 72)
+
+
+def apply_patch(patch_content: str) -> None:
+    """Apply a patch using the patch utility."""
+    subprocess.run(["patch", "-p1"], input=patch_content.encode(), check=True)
+
+
+def replace_file_contents_atomically(  # noqa; DOC501
+    filepath: str | Path,
+    old: str,
+    new: str,
+    count: SupportsIndex = -1,
+    *,
+    content: str | None = None,
+) -> None:
+    """Replace a file atomically with new content.
+
+    Args:
+        filepath: The path to the file to replace.
+        old: The string to replace.
+        new: The string to replace it with.
+        count: The maximum number of occurrences to replace. If negative, all occurrences are
+            replaced.
+        content: The content to replace. If not provided, the file is read from disk.
+
+    The replacement is done atomically by writing to a temporary file and
+    then moving it to the target location.
+    """
+    if isinstance(filepath, str):
+        filepath = Path(filepath)
+
+    if content is None:
+        content = filepath.read_text(encoding="utf-8")
+
+    content = content.replace(old, new, count)
+
+    # Create temporary file in the same directory to ensure atomic move
+    tmp_dir = filepath.parent
+
+    # pylint: disable-next=consider-using-with
+    tmp = tempfile.NamedTemporaryFile(mode="w", dir=tmp_dir, delete=False)
+
+    try:
+        # Copy original file permissions
+        st = os.stat(filepath)
+
+        # Write the new content
+        tmp.write(content)
+
+        # Ensure all data is written to disk
+        tmp.flush()
+        os.fsync(tmp.fileno())
+        tmp.close()
+
+        # Copy original file permissions to the new file
+        os.chmod(tmp.name, st.st_mode)
+
+        # Perform atomic replace
+        os.rename(tmp.name, filepath)
+
+    except BaseException:
+        # Clean up the temporary file in case of errors
+        tmp.close()
+        os.unlink(tmp.name)
+        raise
+
+
+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()

.github/cookiecutter-migrate.template.sh

@@ -187,7 +187,7 @@ These are the steps to create a new release:
 
    ```sh
    cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md
-   cp .github/cookiecutter-migrate.template.sh cookiecutter/migrate.sh
+   cp .github/cookiecutter-migrate.template.py cookiecutter/migrate.py
    ```
 
    Commit the new release notes and migration script, and create a PR (this step

CONTRIBUTING.md

@@ -26,6 +26,7 @@
 * Update the SDK dependency to `1.0.0rc901`.
 * Change `edit_uri` default branch to v0.x.x in mkdocs.yml.
 * Added a new default option `asyncio_default_fixture_loop_scope = "function"` for `pytest-asyncio` as not providing a value is deprecated.
+* The migration script is now written in Python, so it should be (hopefully) more compatible with different OSes.
 
 ## Bug Fixes
 

RELEASE_NOTES.md

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Script to migrate existing projects to new versions of the cookiecutter template.
+
+This script migrates existing projects to new versions of the cookiecutter
+template, removing the need to completely regenerate the project from
+scratch.
+
+To run it, the simplest way is to fetch it from GitHub and run it directly:
+
+    curl -sSL https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-python/<tag>/cookiecutter/migrate.py | python3
+
+Make sure to replace the `<tag>` to the version you want to migrate to in the URL.
+
+For jumping multiple versions you should run the script multiple times, once
+for each version.
+
+And remember to follow any manual instructions for each run.
+"""  # noqa: E501
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import SupportsIndex
+
+
+def apply_patch(patch_content: str) -> None:
+    """Apply a patch using the patch utility."""
+    subprocess.run(["patch", "-p1"], input=patch_content.encode(), check=True)
+
+
+def replace_file_contents_atomically(  # noqa; DOC501
+    filepath: str | Path,
+    old: str,
+    new: str,
+    count: SupportsIndex = -1,
+    *,
+    content: str | None = None,
+) -> None:
+    """Replace a file atomically with new content.
+
+    Args:
+        filepath: The path to the file to replace.
+        old: The string to replace.
+        new: The string to replace it with.
+        count: The maximum number of occurrences to replace. If negative, all occurrences are
+            replaced.
+        content: The content to replace. If not provided, the file is read from disk.
+
+    The replacement is done atomically by writing to a temporary file and
+    then moving it to the target location.
+    """
+    if isinstance(filepath, str):
+        filepath = Path(filepath)
+
+    if content is None:
+        content = filepath.read_text(encoding="utf-8")
+
+    content = content.replace(old, new, count)
+
+    # Create temporary file in the same directory to ensure atomic move
+    tmp_dir = filepath.parent
+
+    # pylint: disable-next=consider-using-with
+    tmp = tempfile.NamedTemporaryFile(mode="w", dir=tmp_dir, delete=False)
+
+    try:
+        # Copy original file permissions
+        st = os.stat(filepath)
+
+        # Write the new content
+        tmp.write(content)
+
+        # Ensure all data is written to disk
+        tmp.flush()
+        os.fsync(tmp.fileno())
+        tmp.close()
+
+        # Copy original file permissions to the new file
+        os.chmod(tmp.name, st.st_mode)
+
+        # Perform atomic replace
+        os.rename(tmp.name, filepath)
+
+    except BaseException:
+        # Clean up the temporary file in case of errors
+        tmp.close()
+        os.unlink(tmp.name)
+        raise
+
+
+def main() -> None:
+    """Run the migration steps."""
+    # Dependabot patch
+    dependabot_yaml = Path(".github/dependabot.yml")
+    print(f"{dependabot_yaml}: Add new grouping for actions/*-artifact updates.")
+    if dependabot_yaml.read_text(encoding="utf-8").find("actions/*-artifact") == -1:
+        apply_patch(
+            """\
+--- a/.github/dependabot.yml
++++ b/.github/dependabot.yml
+@@ -39,3 +39,11 @@ updates:
+     labels:
+       - "part:tooling"
+       - "type:tech-debt"
++    groups:
++      compatible:
++        update-types:
++          - "minor"
++          - "patch"
++      artifacts:
++        patterns:
++          - "actions/*-artifact"
+"""
+        )
+    else:
+        print(f"{dependabot_yaml}: seems to be already up-to-date.")
+    print("=" * 72)
+
+    # Fix labeler configuration
+    labeler_yml = ".github/labeler.yml"
+    print(f"{labeler_yml}: Fix the labeler configuration example.")
+    replace_file_contents_atomically(
+        labeler_yml, "all-glob-to-all-file", "all-globs-to-all-files"
+    )
+    print("=" * 72)
+
+    # Add a separation line like this one after each migration step.
+    print("=" * 72)
+
+
+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()

cookiecutter/migrate.py

@@ -22,8 +22,8 @@ The easiest way to run the migration script is to fetch it from GitHub and run
 it directly.
 
 ```sh
-curl -sSL https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-python/{{ ref_name }}/cookiecutter/migrate.sh \
-	| sh
+curl -sSL https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-python/{{ ref_name }}/cookiecutter/migrate.py \
+	| python3
 ```
 
 Make sure that the version (`{{ ref_name }}`) matches the

cookiecutter/migrate.sh

@@ -11,6 +11,7 @@
     [
         "cookiecutter/hooks",
         "cookiecutter/local_extensions.py",
+        "cookiecutter/migrate.py",
     ]
 )
 nox.configure(config)

docs/user-guide/update-an-existing-project.md

@@ -107,7 +107,7 @@ dev-pytest = [
   "pylint == 3.3.1",       # We need this to check for the examples
   "cookiecutter == 2.6.0", # For checking the cookiecutter scripts
   "jinja2 == 3.1.4",       # For checking the cookiecutter scripts
-  "sybil >= 6.1.1, < 10",   # Should be consistent with the extra-lint-examples dependency
+  "sybil >= 6.1.1, < 10",  # Should be consistent with the extra-lint-examples dependency
 ]
 dev = [
   "frequenz-repo-config[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
@@ -128,7 +128,13 @@ include = '\.pyi?$'
 [tool.isort]
 profile = "black"
 line_length = 88
-src_paths = ["benchmarks", "examples", "src", "tests"]
+src_paths = [
+  "benchmarks",
+  "examples",
+  "src",
+  "tests",
+  "cookiecutter/migrate.py",
+]
 
 [tool.flake8]
 # We give some flexibility to go over 88, there are cases like long URLs or