(chore): automation of towncrier release process (#1626)

Co-authored-by: Philipp A. <flying-sheep@web.de>

Author: ilan-gold

ci/scripts/towncrier_automation.py

@@ -0,0 +1,100 @@
+#!python3
+from __future__ import annotations
+
+import argparse
+import subprocess
+from typing import TYPE_CHECKING
+
+from packaging import version
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+class Args(argparse.Namespace):
+    version: str
+    dry_run: bool
+
+
+def parse_args(argv: Sequence[str] | None = None) -> Args:
+    parser = argparse.ArgumentParser(
+        prog="towncrier-automation",
+        description=(
+            "This script runs towncrier for a given version, "
+            "creates a branch off of the current one, "
+            "and then creates a PR into the original branch with the changes. "
+            "The PR will be backported to main if the current branch is not main."
+        ),
+    )
+    parser.add_argument(
+        "version",
+        type=str,
+        help=(
+            "The new version for the release must have at least three parts, like `major.minor.patch` and no `major.minor`. "
+            "It can have a suffix like `major.minor.patch.dev0` or `major.minor.0rc1`."
+        ),
+    )
+    parser.add_argument(
+        "--dry-run",
+        help="Whether or not to dry-run the actual creation of the pull request",
+        action="store_true",
+    )
+    args = parser.parse_args(argv, Args())
+    if len(version.Version(args.version).release) != 3:
+        raise ValueError(
+            f"Version argument {args.version} must contain major, minor, and patch version."
+        )
+    version.parse(args.version)  # validate
+    return args
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    args = parse_args(argv)
+
+    # Run towncrier
+    subprocess.run(
+        ["towncrier", "build", f"--version={args.version}", "--yes"], check=True
+    )
+
+    # Check if we are on the main branch to know if we need to backport
+    base_branch = subprocess.run(
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout.strip()
+    pr_description = "" if base_branch == "main" else "on-merge: backport to main"
+    branch_name = f"release_notes_{args.version}"
+
+    # Create a new branch + commit
+    subprocess.run(["git", "switch", "-c", branch_name], check=True)
+    subprocess.run(["git", "add", "docs/release-notes"], check=True)
+    pr_title = f"(chore): generate {args.version} release notes"
+    subprocess.run(["git", "commit", "-m", pr_title], check=True)
+
+    # Create a PR
+    subprocess.run(
+        [
+            "gh",
+            "pr",
+            "create",
+            f"--base={base_branch}",
+            f"--head={branch_name}",
+            f"--title={pr_title}",
+            f"--body={pr_description}",
+            *(["--dry-run"] if args.dry_run else []),
+        ],
+        check=True,
+    )
+
+    # Enable auto-merge
+    if not args.dry_run:
+        subprocess.run(
+            ["gh", "pr", "merge", branch_name, "--auto", "--squash"], check=True
+        )
+    else:
+        print("Dry run, not merging")
+
+
+if __name__ == "__main__":
+    main()

docs/contributing.md

@@ -6,6 +6,21 @@ AnnData follows the development practices outlined in the [Scanpy contribution g
 .. include:: _key_contributors.rst
 ```
 
+## Release Notes
+
+AnnData differs from `scanpy` (for now) in how its releases are done.
+It uses [towncrier][] to build its changelog.
+We have set up some automation around this process.
+To run `towncrier`, create a `PR` into the base branch of the release with the compiled changelog, and backport to `main` if needed (i.e., the base branch is something like `0.10.x`), run
+
+```shell
+hatch run towncrier:build X.Y.Z
+```
+
+You may add the option `--dry-run` at the end to do the local steps without pushing to Github, although the push will be mocked via [`gh pr --dry-run`](https://cli.github.com/manual/gh_pr_create).
+
+[towncrier]: https://towncrier.readthedocs.io/en/stable/
+
 ## CI
 
 ### GPU CI

hatch.toml

@@ -9,3 +9,7 @@ dependencies = ["setuptools"]  # https://bitbucket.org/pybtex-devs/pybtex/issues
 [envs.docs.scripts]
 build = "sphinx-build -M html docs docs/_build -W --keep-going {args}"
 clean = "git clean -fX -- docs"
+
+[envs.towncrier.scripts]
+build = "python3 ci/scripts/towncrier_automation.py {args}"
+clean = "git restore --source=HEAD --staged --worktree -- docs/release-notes"

pyproject.toml

@@ -170,9 +170,11 @@ select = [
     "E",   # Error detected by Pycodestyle
     "F",   # Errors detected by Pyflakes
     "W",   # Warning detected by Pycodestyle
+    "PLW", # Pylint
     "UP",  # pyupgrade
     "I",   # isort
     "TCH", # manage type checking blocks
+    "TID", # Banned imports
     "ICN", # Follow import conventions
     "PTH", # Pathlib instead of os.path
     "PT",  # Pytest conventions
@@ -184,13 +186,21 @@ ignore = [
     "E731",
     # allow I, O, l as variable names -> I is the identity matrix, i, j, k, l is reasonable indexing notation
     "E741",
+    # We use relative imports from parent modules
+    "TID252",
+    # Shadowing loop variables isn’t a big deal
+    "PLW2901",
 ]
 [tool.ruff.lint.per-file-ignores]
 # E721 comparing types, but we specifically are checking that we aren't getting subtypes (views)
 "tests/test_readwrite.py" = ["E721"]
 [tool.ruff.lint.isort]
 known-first-party = ["anndata"]
 required-imports = ["from __future__ import annotations"]
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"subprocess.call".msg = "Use `subprocess.run([…])` instead"
+"subprocess.check_call".msg = "Use `subprocess.run([…], check=True)` instead"
+"subprocess.check_output".msg = "Use `subprocess.run([…], check=True, capture_output=True)` instead"
 [tool.ruff.lint.flake8-type-checking]
 exempt-modules = []
 strict = true

src/anndata/logging.py

@@ -31,7 +31,7 @@ def get_memory_usage():
         meminfo = process.get_memory_info()
     mem = meminfo[0] / 2**30  # output in GB
     mem_diff = mem
-    global _previous_memory_usage
+    global _previous_memory_usage  # noqa: PLW0603
     if _previous_memory_usage is not None:
         mem_diff = mem - _previous_memory_usage
     _previous_memory_usage = mem