Automate monthly release process

Author: Yonghui-Lee

.github/release/prepare_release.py

@@ -0,0 +1,158 @@
+#!/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."""
+    return run_cmd(["git", "describe", "--tags", "--abbrev=0"])
+
+
+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" or "2025.5.0post1")
+    version_re = re.compile(r"^\d{4}\.\d+\.\d+\S*$")
+
+    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,180 @@
+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_with_suffix(tmp_path):
+    changelog = tmp_path / "changelog.rst"
+    initial_content = """Changelog
+=========
+
+2025.5.0post1
+-------------
+
+* 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
+
+2025.5.0post1
+-------------
+
+* 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"]
+        )