Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

ci(release): generate GitHub release notes from CHANGELOG

xf gongc0c879fb0d13
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 56943b5..ac83850 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -88,10 +88,10 @@ jobs:
run: uv sync --all-extras --dev
- name: Ruff check
- run: uv run ruff check cubeloop/ tests/
+ run: uv run ruff check cubeloop/ tests/ scripts/
- name: Ruff format check
- run: uv run ruff format --check cubeloop/ tests/
+ run: uv run ruff format --check cubeloop/ tests/ scripts/
- name: Mypy
run: uv run mypy cubeloop
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 5276210..54e83e2 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -1,14 +1,56 @@
name: Publish to PyPI
+# A pushed vX.Y.Z tag is the publish trigger. The GitHub Release is created
+# at the end with GITHUB_TOKEN, which does not start another workflow run.
+# PyPI trusted publishing is also pinned to this file, so both stay here.
+# Creating a Release by hand still runs this workflow; its body is replaced
+# from CHANGELOG.md on the tagged commit.
+
on:
+ push:
+ tags:
+ - "v*.*.*"
release:
types: [published]
permissions:
contents: read
+concurrency:
+ group: publish-${{ github.event_name == 'release' && github.event.release.tag_name || github.ref_name }}
+ cancel-in-progress: false
+
+env:
+ RELEASE_TAG: ${{ github.event_name == 'release' && github.event.release.tag_name || github.ref_name }}
+
jobs:
+ release-notes:
+ name: Prepare release notes
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - uses: actions/checkout@v7
+
+ - name: Render changelog and pull requests
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ set -euo pipefail
+ python3 scripts/release-notes.py "$RELEASE_TAG" > release-notes.md
+ gh api -X POST "repos/${GITHUB_REPOSITORY}/releases/generate-notes" \
+ -f tag_name="$RELEASE_TAG" --jq .body > generated-release-notes.md
+ printf '\n---\n\n## Pull requests and contributors\n\n' >> release-notes.md
+ cat generated-release-notes.md >> release-notes.md
+
+ - uses: actions/upload-artifact@v7
+ with:
+ name: release-notes
+ path: release-notes.md
+ if-no-files-found: error
+
build:
+ needs: release-notes
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
@@ -61,3 +103,30 @@ jobs:
uses: pypa/gh-action-pypi-publish@release/v1
with:
skip-existing: true
+
+ github-release:
+ name: Create or update GitHub release
+ needs: publish-pypi
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ fetch-depth: 0
+
+ - uses: actions/download-artifact@v8
+ with:
+ name: release-notes
+ path: .
+
+ - name: Create or update GitHub release
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ set -euo pipefail
+ if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
+ gh release edit "$RELEASE_TAG" --notes-file release-notes.md
+ else
+ gh release create "$RELEASE_TAG" --verify-tag --notes-file release-notes.md
+ fi
diff --git a/dev/runbooks/cut-doc-version.md b/dev/runbooks/cut-doc-version.md
index ea6a65f..2eb6a8d 100644
--- a/dev/runbooks/cut-doc-version.md
+++ b/dev/runbooks/cut-doc-version.md
@@ -289,6 +289,18 @@ Then in the rendered site (`pnpm start` or the preview deploy):
## After the cut
-The release itself (tag, GitHub Release, PyPI publish) is a separate runbook
-— but the order is: cut docs → bump pyproject.toml if not already → merge
-PR → tag → push tag → create GitHub Release (triggers PyPI publish).
+Push the annotated `vX.Y.Z` tag only after main CI and the docs deploy for
+the merge commit have succeeded. `.github/workflows/publish.yml` runs on
+that tag. It publishes both packages to TestPyPI and then PyPI, then creates
+the GitHub Release.
+
+The Release body is the matching `## [X.Y.Z] - YYYY-MM-DD` section of
+`CHANGELOG.md`, followed by the pull requests merged since the previous
+release. The workflow stops before publishing if that section is missing or
+empty, or if `pyproject.toml` and `compat/cubepi/pyproject.toml` are not
+both exactly `X.Y.Z`. Keep the changelog on the tagged commit. A rerun reads
+that commit and replaces the Release body.
+
+A Release created by hand still starts the same workflow, and the generated
+body replaces whatever was typed in. The usual path is to push the tag and
+let the workflow create the Release.
diff --git a/scripts/release-notes.py b/scripts/release-notes.py
new file mode 100644
index 0000000..2dc4a11
--- /dev/null
+++ b/scripts/release-notes.py
@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Render one CHANGELOG.md version as GitHub release notes.
+
+The release workflow refuses to publish when this command fails. The tag,
+both package versions, and a non-empty dated changelog section must agree.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import tomllib
+from pathlib import Path
+
+_TAG = re.compile(r"v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\Z")
+_LINK_REF = re.compile(r"^\[[^\]\n]+\]: \S+\Z")
+_PACKAGES = (
+ Path("pyproject.toml"),
+ Path("compat/cubepi/pyproject.toml"),
+)
+
+
+def release_version(tag: str) -> str:
+ if _TAG.fullmatch(tag) is None:
+ raise ValueError("Expected a release tag in the form v<major>.<minor>.<patch>")
+ return tag[1:]
+
+
+def render_release_notes(changelog: str, tag: str) -> str:
+ """Return the dated section for ``tag``, including its heading."""
+ version = release_version(tag)
+ heading = re.compile(
+ rf"^## \[{re.escape(version)}\] - \d{{4}}-\d{{2}}-\d{{2}}[^\S\n]*$",
+ re.MULTILINE,
+ )
+ found = heading.search(changelog)
+ if found is None:
+ raise ValueError(f"CHANGELOG.md has no '## [{version}] - YYYY-MM-DD' section")
+ rest = changelog[found.end() :]
+ following = re.search(r"^## ", rest, re.MULTILINE)
+ if following is not None:
+ rest = rest[: following.start()]
+ lines = rest.splitlines()
+ while lines and (not lines[-1].strip() or _LINK_REF.fullmatch(lines[-1])):
+ lines.pop()
+ body = "\n".join(lines).strip()
+ if not body:
+ raise ValueError(f"CHANGELOG.md section for {version} is empty")
+ return f"{found.group(0).strip()}\n\n{body}\n"
+
+
+def assert_package_versions(root: Path, tag: str) -> None:
+ """Require every released package version to equal ``tag``."""
+ version = release_version(tag)
+ for relative in _PACKAGES:
+ path = root / relative
+ try:
+ with path.open("rb") as handle:
+ data = tomllib.load(handle)
+ except OSError as error:
+ raise ValueError(f"Cannot read {relative}") from error
+ except tomllib.TOMLDecodeError as error:
+ raise ValueError(f"Cannot parse {relative}") from error
+ project = data.get("project")
+ found = project.get("version") if isinstance(project, dict) else None
+ if not isinstance(found, str) or found == "":
+ raise ValueError(f"{relative} is missing project.version")
+ if found != version:
+ raise ValueError(f"{relative} version is {found}, release tag is {tag}")
+
+
+def prepare_release_notes(root: Path, tag: str) -> str:
+ assert_package_versions(root, tag)
+ try:
+ changelog = (root / "CHANGELOG.md").read_text(encoding="utf-8")
+ except OSError as error:
+ raise ValueError("Cannot read CHANGELOG.md") from error
+ return render_release_notes(changelog, tag)
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("tag")
+ args = parser.parse_args()
+ root = Path(__file__).resolve().parents[1]
+ try:
+ print(prepare_release_notes(root, args.tag), end="")
+ except (OSError, ValueError) as error:
+ parser.exit(1, f"Cannot prepare release notes: {error}\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_release_notes.py b/tests/test_release_notes.py
new file mode 100644
index 0000000..ceb63e4
--- /dev/null
+++ b/tests/test_release_notes.py
@@ -0,0 +1,131 @@
+"""The release tag, package versions, and changelog section stay in lockstep."""
+
+from __future__ import annotations
+
+import importlib.util
+import tomllib
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_renderer() -> ModuleType:
+ path = ROOT / "scripts" / "release-notes.py"
+ spec = importlib.util.spec_from_file_location("release_notes", path)
+ assert spec is not None and spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
[email protected](scope="module")
+def renderer() -> ModuleType:
+ return load_renderer()
+
+
+def write_release(root: Path, changelog: str, cubeloop: str, cubepi: str) -> None:
+ (root / "CHANGELOG.md").write_text(changelog, encoding="utf-8")
+ (root / "pyproject.toml").write_text(
+ f'[project]\nname = "cubeloop"\nversion = "{cubeloop}"\n',
+ encoding="utf-8",
+ )
+ package = root / "compat" / "cubepi"
+ package.mkdir(parents=True)
+ (package / "pyproject.toml").write_text(
+ f'[project]\nname = "cubepi"\nversion = "{cubepi}"\n',
+ encoding="utf-8",
+ )
+
+
+def test_renders_only_the_matching_version_section(
+ renderer: ModuleType, tmp_path: Path
+) -> None:
+ write_release(
+ tmp_path,
+ """# Changelog
+
+## [Unreleased]
+
+## [1.2.3] - 2026-01-02
+
+### Fixed
+
+- The useful fix (`#9`).
+
+[example](../guide.md)
+
+[1.2.3]: https://example.com/compare/1.2.3
+[Unreleased]: https://example.com/unreleased
+
+## [1.2.2] - 2026-01-01
+
+### Added
+
+- Older feature.
+""",
+ "1.2.3",
+ "1.2.3",
+ )
+ notes = renderer.prepare_release_notes(tmp_path, "v1.2.3")
+ assert notes == (
+ "## [1.2.3] - 2026-01-02\n"
+ "\n"
+ "### Fixed\n"
+ "\n"
+ "- The useful fix (`#9`).\n"
+ "\n"
+ "[example](../guide.md)\n"
+ )
+
+
+def test_rejects_invalid_tags(renderer: ModuleType) -> None:
+ for tag in ("0.15.1", "v0.15", "v01.2.3", "v1.2.3-rc1", "../v1.2.3"):
+ with pytest.raises(ValueError, match="v<major>"):
+ renderer.release_version(tag)
+
+
+def test_missing_or_empty_section_blocks_publication(
+ renderer: ModuleType, tmp_path: Path
+) -> None:
+ write_release(
+ tmp_path,
+ "## [1.2.3] - 2026-01-02\n\n## [1.2.2] - 2026-01-01\n\n- Older.\n",
+ "1.2.3",
+ "1.2.3",
+ )
+ with pytest.raises(ValueError, match="empty"):
+ renderer.prepare_release_notes(tmp_path, "v1.2.3")
+
+ (tmp_path / "CHANGELOG.md").write_text(
+ "## [Unreleased]\n\n- Not this release.\n", encoding="utf-8"
+ )
+ with pytest.raises(ValueError, match="no '## \\[1.2.3\\]"):
+ renderer.prepare_release_notes(tmp_path, "v1.2.3")
+
+
+def test_package_version_must_match_the_tag(
+ renderer: ModuleType, tmp_path: Path
+) -> None:
+ write_release(
+ tmp_path,
+ "## [1.2.3] - 2026-01-02\n\n- Ready.\n",
+ "1.2.3",
+ "1.2.2",
+ )
+ with pytest.raises(ValueError, match="compat/cubepi/pyproject.toml"):
+ renderer.prepare_release_notes(tmp_path, "v1.2.3")
+
+
+def test_checked_out_tree_renders_its_package_version(renderer: ModuleType) -> None:
+ with (ROOT / "pyproject.toml").open("rb") as handle:
+ version = tomllib.load(handle)["project"]["version"]
+ notes = renderer.prepare_release_notes(ROOT, f"v{version}")
+ assert notes.startswith(f"## [{version}] - ")
+ assert "\n### " in notes
+ assert "https://github.com/cubeplexai/cubeloop/compare/" not in notes
+
+ with pytest.raises(ValueError, match="pyproject.toml version is"):
+ renderer.prepare_release_notes(ROOT, "v0.0.0")