Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 92 additions & 0 deletions .github/release-drafter.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
---
name-template: "v$RESOLVED_VERSION"
tag-template: "v$RESOLVED_VERSION"
include-pre-releases: true
template: |
# Changelog
$CHANGES

See details of [all code changes](https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...v$RESOLVED_VERSION) since previous release

exclude-labels:
- "skip-changelog"

categories:
- title: "💥 Breaking Changes"
labels:
- "breaking"
- "major"
- "release:major"
- title: "🚀 Features"
labels:
- "feature"
- "enhancement"
- "minor"
- "release:minor"
- title: "🐛 Bug Fixes"
labels:
- "fix"
- "bugfix"
- "bug"
- "patch"
- "release:patch"
- title: "🧰 Maintenance"
labels:
- "infrastructure"
- "automation"
- "documentation"
- "dependencies"
- "maintenance"
- "revert"
- title: "🏎 Performance"
labels:
- "performance"

change-template: "- $TITLE @$AUTHOR (#$NUMBER)"

version-resolver:
major:
labels:
- "breaking"
- "major"
- "release:major"
minor:
labels:
- "feature"
- "enhancement"
- "minor"
- "release:minor"
patch:
labels:
- "fix"
- "documentation"
- "maintenance"
- "patch"
- "release:patch"
default: patch

autolabeler:
- label: "automation"
title:
- "/^(build|ci|perf|refactor|test).*/i"
- label: "enhancement"
title:
- "/^(style).*/i"
- label: "documentation"
title:
- "/^(docs).*/i"
- label: "feature"
title:
- "/^(feat).*/i"
- label: "fix"
title:
- "/^(fix).*/i"
- label: "infrastructure"
title:
- "/^(infrastructure).*/i"
- label: "maintenance"
title:
- "/^(chore|maintenance).*/i"
- label: "revert"
title:
- "/^(revert).*/i"
72 changes: 72 additions & 0 deletions .github/workflows/prepare-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
name: Prepare Release

on:
workflow_dispatch:
inputs:
version:
description: "Release version to prepare (X.Y.Z without v prefix)"
required: true
type: string

permissions:
contents: read

jobs:
prepare:
name: Prepare Release PR
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
enable-cache: false

- name: Validate target version and active draft
env:
TARGET_VERSION: ${{ inputs.version }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
REPOSITORY: ${{ github.repository }}
run: |
uv run python tools/validate_release_version.py \
--version "$TARGET_VERSION" \
--repo "$REPOSITORY"

- name: Update version and lockfile
env:
TARGET_VERSION: ${{ inputs.version }}
run: |
uv version "$TARGET_VERSION"
uv lock --check

- name: Verify build and test suite
run: |
uv run poe test
uv run poe lint
uv run ruff format --check .
uv run poe typecheck
uv build

- name: Create or update release preparation pull request
uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7.0.8
with:
token: ${{ secrets.GITHUB_TOKEN }}
branch: release-prep/v${{ inputs.version }}
delete-branch: false
title: "chore: prepare release v${{ inputs.version }}"
body: |
Release preparation for version `${{ inputs.version }}`.

This PR updates the package version in `pyproject.toml` and ensures `uv.lock` remains synchronized.

- Tag: `v${{ inputs.version }}`
- Excluded from release notes and version calculation via `skip-changelog`.
commit-message: "chore: prepare release v${{ inputs.version }}"
labels: |
release
skip-changelog
101 changes: 71 additions & 30 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,35 +1,77 @@
name: Release
---
name: "Release"

on:
workflow_dispatch:
push:
tags: ["v*"]
branches:
- main

permissions:
contents: read
concurrency:
group: release
cancel-in-progress: false
queue: max

jobs:
build:
name: Build and verify
release:
permissions:
contents: write # Create release and push tags
pull-requests: read # Read PR labels for release-drafter
packages: write # Push container image to ghcr.io
id-token: write # Federate for artifact attestation
attestations: write # Generate build provenance attestations
discussions: write # Create release announcement discussion
uses: github-community-projects/ospo-reusable-workflows/.github/workflows/release.yaml@ee8277bd76ef808b3a6e0bdd1f5a46a520a12c5d # v2.3.1
with:
publish: true
release-config-name: release-drafter.yml
release-only-with-label: true
secrets:
github-token: ${{ secrets.GITHUB_TOKEN }}

publish-pypi:
name: Build and publish to PyPI
needs: release
if: needs.release.outputs.full-tag != ''
runs-on: ubuntu-latest
environment: pypi
permissions:
contents: read
id-token: write # For PyPI trusted publishing
steps:
- name: Validate release tag format
env:
TAG: ${{ needs.release.outputs.full-tag }}
run: |
uv run python -c '
import os, re, sys
tag = os.environ.get("TAG", "")
if not re.match(r"^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$", tag):
print(f"::error::Release tag \"{tag}\" must follow stable semver format vX.Y.Z", file=sys.stderr)
sys.exit(1)
'

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ needs.release.outputs.full-tag }}
persist-credentials: false

- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
# The release path builds the artifacts that get published, so it must
# not restore a cache that a pull request workflow could have poisoned.
enable-cache: false

- run: uv sync --frozen

- name: Verify the tag matches the static version
env:
TAG: ${{ needs.release.outputs.full-tag }}
run: |
# Artifacts must never ship as 0.0.0, and the tag is the only thing
# that should ever disagree with pyproject.toml.
declared="$(uv run python -c 'import tomllib,pathlib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
tagged="${GITHUB_REF_NAME#v}"
tagged="${TAG#v}"
test "$declared" != "0.0.0" || { echo "::error::version is 0.0.0"; exit 1; }
test "$declared" = "$tagged" || {
echo "::error::tag $tagged does not match pyproject version $declared"; exit 1; }

- run: uv run pytest -q
- name: Regenerate models from the vendored schema
run: uv run poe generate
Expand All @@ -38,38 +80,37 @@ jobs:
- run: uv run ruff format --check .
- run: uv run poe typecheck
- run: uv build
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: dist
path: dist/

publish-pypi:
name: Publish to PyPI
needs: build
runs-on: ubuntu-latest
environment: pypi
permissions:
# Trusted publishing: mint a short-lived OIDC token instead of holding a
# long-lived PyPI API token in repository secrets.
id-token: write
steps:
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: dist
path: dist/
- name: Verify built artifact version matches pyproject.toml
env:
TAG: ${{ needs.release.outputs.full-tag }}
run: |
version="${TAG#v}"
test -f "dist/gemara_python-${version}.tar.gz" || {
echo "::error::Source archive dist/gemara_python-${version}.tar.gz missing"; exit 1; }
test -f "dist/gemara_python-${version}-py3-none-any.whl" || {
echo "::error::Wheel dist/gemara_python-${version}-py3-none-any.whl missing"; exit 1; }

- uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

verify-published:
name: Test the PyPI package
needs: publish-pypi
needs: [release, publish-pypi]
if: needs.release.outputs.full-tag != ''
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ needs.release.outputs.full-tag }}
persist-credentials: false

- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
enable-cache: false

- name: Wait for PyPI index propagation
run: sleep 60

- uses: $/.github/actions/verify-published-package
51 changes: 47 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,50 @@ Publishing uses Trusted Publishing (OIDC); no API tokens are stored. The
publisher registered on each index.

- **Rehearse:** run the *Publish to TestPyPI* workflow manually
(`workflow_dispatch`) against any ref or push a test tag matching `test-vX.Y.X`.
- **Release:** set `version` in `pyproject.toml`, then push a matching `vX.Y.Z`
tag. The release workflow refuses a tag that disagrees with that version, and
refuses `0.0.0` outright.
(`workflow_dispatch`) against any ref or push a test tag matching `test-vX.Y.Z`.

### Release Versioning Policy

Release Drafter automatically maintains a draft release on GitHub as pull requests are merged into `main`. The next version is resolved from PR labels using SemVer:

- `release:major` / `major` / `breaking`: increments major version (`X+1.0.0`, e.g. `0.1.0` -> `1.0.0` or `1.2.3` -> `2.0.0`).
- `release:minor` / `minor` / `feature` / `enhancement`: increments minor version (`X.Y+1.0`, e.g. `0.1.0` -> `0.2.0`).
- `release:patch` / `patch` / `fix`: increments patch version (`X.Y.Z+1`, e.g. `0.1.0` -> `0.1.1`).

**Rules & Precedence:**
- **Baseline and pre-releases:** `include-pre-releases: true` is configured so that the existing `v0.1.0` pre-release acts as the baseline for change aggregation and next-version resolution.
- **Highest increment wins:** When multiple merged PRs carry different release labels, the highest bump applies (`major` > `minor` > `patch`).
- **Unlabeled PR fallback:** Pull requests merged without a release label default to a `patch` increment.
- **Exclusion of release preparation PRs:** Pull requests labeled `skip-changelog` (such as automated release-preparation PRs) are excluded from both changelog notes and version calculation.

### Maintainer Release Process

This repository uses the shared organization release workflow from [`github-community-projects/ospo-reusable-workflows`](https://github.com/github-community-projects/ospo-reusable-workflows) (pinned at `v2.3.1`).

1. **Check the Draft Release:**
Inspect the active draft release under GitHub Releases. Verify the draft release notes and resolved tag (e.g., `v0.2.0`).

2. **Run the Version-Preparation Workflow:**
Trigger the *Prepare Release* workflow (`.github/workflows/prepare-release.yml`) via `workflow_dispatch`, passing the target version without the `v` prefix (e.g. `0.2.0`).
The workflow:
- Validates that the target version is a stable `X.Y.Z` semver, is strictly newer than the latest published release, and matches the active draft tag.
- Updates `pyproject.toml` with `uv version "<version>"` and verifies `uv.lock` with `uv lock --check`.
- Runs test, lint, formatting, typechecking, and package build checks.
- Opens or updates a release-preparation pull request targeting `main` with the `release` and `skip-changelog` labels on branch `release-prep/v<version>`. Re-running for the same version updates the existing PR without creating duplicates.

*Note on workflow permissions:* If the PR is created using GitHub Actions default `GITHUB_TOKEN`, GitHub branch protection or actions policies may require a maintainer approval before CI runs on the PR.

3. **Review and Merge the Version PR:**
Review and merge the release-preparation PR into `main` with the `release` label.

4. **Automated Release and PyPI Publishing:**
When the version PR carrying the `release` label is merged to `main`, `.github/workflows/release.yml` executes:
- Runs `github-community-projects/ospo-reusable-workflows/.github/workflows/release.yaml` to finalize and publish the GitHub release with tags `vX.Y.Z` and `vX`.
- Directly executes the chained `publish-pypi` job in the same run to verify and publish the package to PyPI via Trusted Publishing (`id-token: write`).
- Runs `verify-published` to test the published package on the live PyPI index.

### Troubleshooting & Mismatch Resolution

- **Draft / Tag / Package version mismatch:** If `pyproject.toml` does not match the published release tag `vX.Y.Z`, the release workflow fails immediately before building or publishing. Re-run *Prepare Release* for the matching version and ensure the PR is merged into `main` before publishing the release.
- **Lockfile mismatch:** If `uv.lock` is out of sync, `uv lock --check` fails during the preparation workflow. Run `uv lock` locally or re-sync dependencies.
- **Already published:** The validation script and PyPI trusted publishing prevent re-publishing an existing version.
Loading