Automate monthly release process

Author: Yonghui-Lee

.github/release/prepare_release.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+import datetime
+import os
+import re
+import subprocess
+import sys
+
+
+def run_cmd(cmd_args):
+    """Runs a terminal command without shell=True to avoid injection risks."""
+    result = subprocess.run(cmd_args, capture_output=True, text=True, check=True)
+    return result.stdout.strip()
+
+
+def get_latest_tag():
+    """Gets the latest git tag reachable from HEAD."""
+    try:
+        return run_cmd(["git", "describe", "--tags", "--abbrev=0"])
+    except subprocess.CalledProcessError as e:
+        print(f"Error getting latest tag: {e.stderr}", file=sys.stderr)
+        raise
+
+
+def parse_version(version_str):
+    """Parses a version string like YYYY.M.PATCH[-suffix] into a tuple of integers."""
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)", version_str)
+    if not match:
+        raise ValueError(
+            f"Version '{version_str}' does not match expected CalVer pattern YYYY.M.PATCH"
+        )
+    return tuple(map(int, match.groups()))
+
+
+def calculate_next_version(latest_tag):
+    """Calculates the next CalVer version based on the latest tag and current date."""
+    latest_ver = parse_version(latest_tag)
+    tag_year, tag_month, tag_patch = latest_ver
+
+    now = datetime.datetime.now(datetime.timezone.utc)
+    current_year = now.year
+    current_month = now.month
+
+    if tag_year == current_year and tag_month == current_month:
+        # Same month, increment patch
+        next_patch = tag_patch + 1
+    else:
+        # New month, reset patch to 0
+        next_patch = 0
+
+    next_version_str = f"{current_year}.{current_month}.{next_patch}"
+    next_ver = parse_version(next_version_str)
+
+    # Safety guard: Ensure we never release a version older or equal to the last one
+    if next_ver <= latest_ver:
+        raise ValueError(
+            f"Calculated next version ({next_version_str}) is not newer than "
+            f"the latest tag ({latest_tag}). Potential version regression!"
+        )
+
+    return next_version_str
+
+
+def get_changelog_entries(latest_tag):
+    """Retrieves all non-merge commit subjects since the latest tag."""
+    cmd_args = [
+        "git",
+        "log",
+        f"{latest_tag}..HEAD",
+        "--no-merges",
+        "--pretty=format:* %s",
+    ]
+    log_output = run_cmd(cmd_args)
+    if not log_output:
+        return ["* No changes (released in sync with fsspec)."]
+    return log_output.split("\n")
+
+
+def update_changelog_file(changelog_path, version, entries):
+    """Inserts a new release section with version and commit logs into the changelog.rst file."""
+    if not os.path.exists(changelog_path):
+        raise FileNotFoundError(f"Changelog file not found at {changelog_path}")
+
+    with open(changelog_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    lines = content.split("\n")
+    insert_idx = -1
+    # Regex to match version header (e.g., "2026.4.0")
+    version_re = re.compile(r"^\d{4}\.\d+\.\d+$")
+
+    for i in range(len(lines) - 1):
+        if (
+            version_re.match(lines[i])
+            and lines[i + 1].startswith("---")
+            and len(lines[i + 1]) >= len(lines[i])
+        ):
+            insert_idx = i
+            break
+
+    if insert_idx == -1:
+        # If we couldn't find a version header, we might be in an empty or differently formatted file.
+        # In this case, we raise an error.
+        raise ValueError(
+            "Could not find a valid version header in changelog to insert before."
+        )
+
+    # Prepare the new section
+    version_underline = "-" * len(version)
+    new_section_lines = (
+        [
+            version,
+            version_underline,
+            "",
+        ]
+        + entries
+        + [""]
+    )
+
+    # Insert the new section. We want to keep an empty line between sections.
+    # The first version header we found should be pushed down.
+    # We insert before the version line.
+    updated_lines = lines[:insert_idx] + new_section_lines + lines[insert_idx:]
+
+    with open(changelog_path, "w", encoding="utf-8") as f:
+        f.write("\n".join(updated_lines))
+
+    print(f"Successfully updated changelog with version {version}")
+
+
+def main():
+    changelog_path = "docs/source/changelog.rst"
+
+    try:
+        # 1. Retrieve the latest release tag from Git
+        latest_tag = get_latest_tag()
+        print(f"Latest tag found: {latest_tag}")
+
+        # 2. Calculate the next CalVer version and perform regression checks
+        next_version = calculate_next_version(latest_tag)
+        print(f"Calculated next version: {next_version}")
+
+        # 3. Fetch the changelog entries (non-merge commits) since the last tag
+        entries = get_changelog_entries(latest_tag)
+        print(f"Found {len(entries)} changelog entries.")
+
+        # 4. Update the changelog file in place with the new release section
+        update_changelog_file(changelog_path, next_version, entries)
+
+        # 5. Output the version to GITHUB_ENV for downstream workflow consumption
+        print(f"NEXT_VERSION={next_version}")
+        if "GITHUB_ENV" in os.environ:
+            with open(os.environ["GITHUB_ENV"], "a") as gh_env:
+                gh_env.write(f"VERSION={next_version}\n")
+                gh_env.write(f"BRANCH_NAME=release-{next_version}\n")
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

.github/release/test_prepare_release.py

@@ -0,0 +1,150 @@
+import datetime
+import os
+import subprocess
+import sys
+
+import pytest
+
+# Add the directory containing prepare_release.py to the path
+sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))
+import prepare_release
+
+
+def test_parse_version():
+    assert prepare_release.parse_version("2026.4.0") == (2026, 4, 0)
+    assert prepare_release.parse_version("2026.12.5-post1") == (2026, 12, 5)
+
+    with pytest.raises(ValueError, match="does not match expected CalVer pattern"):
+        prepare_release.parse_version("v2026.4.0")
+    with pytest.raises(ValueError, match="does not match expected CalVer pattern"):
+        prepare_release.parse_version("abc")
+    with pytest.raises(ValueError, match="does not match expected CalVer pattern"):
+        prepare_release.parse_version("2026.4")
+
+
+def test_calculate_next_version(monkeypatch):
+    class MockDatetime(datetime.datetime):
+        @classmethod
+        def now(cls, tz=None):
+            return cls(2026, 4, 15, tzinfo=datetime.timezone.utc)
+
+    monkeypatch.setattr("prepare_release.datetime.datetime", MockDatetime)
+
+    # Same month: increment patch
+    assert prepare_release.calculate_next_version("2026.4.0") == "2026.4.1"
+    assert prepare_release.calculate_next_version("2026.4.5") == "2026.4.6"
+
+    # New month: reset patch to 0
+    assert prepare_release.calculate_next_version("2026.3.5") == "2026.4.0"
+    assert prepare_release.calculate_next_version("2025.12.10") == "2026.4.0"
+
+    # Regression guard: new version (2026.4.0) must be newer than latest tag (2026.5.0)
+    with pytest.raises(ValueError, match="Potential version regression"):
+        prepare_release.calculate_next_version("2026.5.0")
+
+    # Regression guard: new version (2026.4.0) must be newer than latest tag (2027.1.0)
+    with pytest.raises(ValueError, match="Potential version regression"):
+        prepare_release.calculate_next_version("2027.1.0")
+
+
+def test_get_latest_tag(monkeypatch):
+    # Success case
+    monkeypatch.setattr("prepare_release.run_cmd", lambda args: "2026.4.0")
+    assert prepare_release.get_latest_tag() == "2026.4.0"
+
+    # Error case
+    def mock_run_cmd_fail(args):
+        raise subprocess.CalledProcessError(1, args, stderr="git error")
+
+    monkeypatch.setattr("prepare_release.run_cmd", mock_run_cmd_fail)
+    with pytest.raises(subprocess.CalledProcessError):
+        prepare_release.get_latest_tag()
+
+
+def test_get_changelog_entries(monkeypatch):
+    # Success case with commits
+    def mock_run_cmd_commits(args):
+        assert args == [
+            "git",
+            "log",
+            "2026.4.0..HEAD",
+            "--no-merges",
+            "--pretty=format:* %s",
+        ]
+        return "* Commit 1 (abc1234)\n* Commit 2 (def5678)"
+
+    monkeypatch.setattr("prepare_release.run_cmd", mock_run_cmd_commits)
+    entries = prepare_release.get_changelog_entries("2026.4.0")
+    assert entries == ["* Commit 1 (abc1234)", "* Commit 2 (def5678)"]
+
+    # Success case with no commits (empty string)
+    monkeypatch.setattr("prepare_release.run_cmd", lambda args: "")
+    entries = prepare_release.get_changelog_entries("2026.4.0")
+    assert entries == ["* No changes (released in sync with fsspec)."]
+
+    # Error case: a git failure must propagate, not be swallowed into an
+    # empty/placeholder changelog.
+    def mock_run_cmd_fail(args):
+        raise subprocess.CalledProcessError(1, args, stderr="git log error")
+
+    monkeypatch.setattr("prepare_release.run_cmd", mock_run_cmd_fail)
+    with pytest.raises(subprocess.CalledProcessError):
+        prepare_release.get_changelog_entries("2026.4.0")
+
+
+def test_update_changelog_file(tmp_path):
+    changelog = tmp_path / "changelog.rst"
+    initial_content = """Changelog
+=========
+
+2026.4.0
+--------
+
+* Previous change
+"""
+    changelog.write_text(initial_content, encoding="utf-8")
+
+    prepare_release.update_changelog_file(str(changelog), "2026.4.1", ["* New feature"])
+
+    expected_content = """Changelog
+=========
+
+2026.4.1
+--------
+
+* New feature
+
+2026.4.0
+--------
+
+* Previous change
+"""
+    assert changelog.read_text(encoding="utf-8") == expected_content
+
+
+def test_update_changelog_file_no_header(tmp_path):
+    changelog = tmp_path / "changelog.rst"
+    changelog.write_text("No header here", encoding="utf-8")
+
+    with pytest.raises(ValueError, match="Could not find a valid version header"):
+        prepare_release.update_changelog_file(
+            str(changelog), "2026.4.1", ["* New feature"]
+        )
+
+
+def test_update_changelog_file_short_underline(tmp_path):
+    changelog = tmp_path / "changelog.rst"
+    initial_content = """Changelog
+=========
+
+2026.4.0
+--
+
+* Previous change
+"""
+    changelog.write_text(initial_content, encoding="utf-8")
+
+    with pytest.raises(ValueError, match="Could not find a valid version header"):
+        prepare_release.update_changelog_file(
+            str(changelog), "2026.4.1", ["* New feature"]
+        )

.github/workflows/release-on-merge.yml

@@ -0,0 +1,67 @@
+name: Release on Merge
+
+# Monthly release orchestrator (Publishing Phase):
+#   1. Triggers when a Pull Request is closed and merged into main.
+#   2. If it is a release PR (has 'autorelease' label), it extracts the version.
+#   3. Creates and pushes the Git tag for that version.
+#   4. Calls the reusable release.yml workflow to build and publish to PyPI.
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+
+jobs:
+  tag:
+    # Run only if the PR was merged, and it has the 'autorelease' label,
+    # and the title matches our release convention.
+    if: |
+      github.event.pull_request.merged == true &&
+      contains(github.event.pull_request.labels.*.name, 'autorelease') &&
+      startsWith(github.event.pull_request.title, 'chore: release ')
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      version: ${{ steps.tagger.outputs.version }}
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Create and Push Tag
+        id: tagger
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          # Extract version from "chore: release YYYY.M.PATCH"
+          VERSION=$(echo "$PR_TITLE" | sed 's/chore: release //')
+          if [[ ! "$VERSION" =~ ^[0-9]{4}\.[0-9]+\.[0-9]+(-[a-zA-Z0-9]+)?$ ]]; then
+            echo "Error: Extracted version '$VERSION' is invalid."
+            exit 1
+          fi
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
+          echo "Creating and pushing tag for version: $VERSION"
+          git tag -a "$VERSION" -m "Release $VERSION"
+          git push origin "$VERSION"
+          echo "Successfully pushed tag $VERSION"
+
+  publish:
+    needs: tag
+    permissions:
+      contents: write
+      id-token: write
+    uses: ./.github/workflows/release.yml
+    with:
+      ref: ${{ needs.tag.outputs.version }}
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}