Skip to content

Release on a tag through trusted publishing, with the checks that were memory before - #5

Open
r0ny123 wants to merge 1 commit into
familiary:masterfrom
r0ny123:release/modernize-release-workflow
Open

r0ny123 wants to merge 1 commit into
familiary:masterfrom
r0ny123:release/modernize-release-workflow

Conversation

@r0ny123

@r0ny123 r0ny123 commented Sep 13, 2026

Copy link
Copy Markdown
Collaborator

Releasing picblocks is make publish with an API token. There are no GitHub releases, the release history lives in the README, and nothing checks that a tag names the version pyproject.toml declares before a version number is consumed on PyPI.

This is the seventh pull request giving the MCRIT ecosystem one release process — the same guard, the same tag-triggered workflow, the same changelog check, and a RELEASING.md in each repository stating only the values that differ. A maintainer learns it once. picblocks sits between smda and mcrit in that chain (smda>=4.2.13 in, picblocks>=1.1.2 out).

Architecture

The hand-written CHANGELOG.md is the single stream of change information. The README "Version History" (nine releases) moves verbatim into it under ## Older releases, below a Keep a Changelog ## [Unreleased] section; the README links to it. Every PR that touches picblocks/ or pyproject.toml adds its own bullet, or carries the no-changelog label; a new Changelog check enforces that (read-only token, no PR content executed, Dependabot exempt). At release time the version's section is the release notes, and GitHub's generated list of merged PRs and contributors is appended under it. .github/release.yml groups the dependency bumps.

Versioning is Semantic Versioning over the block report format, the database format and the scores the matcher reports — the two things v2.0.0 and v2.1.0 already treated as breaking. pyproject.toml is the only place the version is declared (#4 already made it so); the guard reads it and the workflow refuses a tag that does not match.

What pushing vX.Y.Z does now

.github/workflows/publish-release.yml:

job what it does
verify refuses unless the tag matches pyproject.toml, CHANGELOG.md has a ## [X.Y.Z] - <date> section (written out as the notes), the commit is an ancestor of master, and the Tests workflow concluded success on that commit
build python -m build in isolation, twine check --strict, then installs the wheel into a clean venv carrying only the declared runtime dependency and imports the hasher and matcher with python -P, so the checkout cannot stand in for the wheel
publish pypa/gh-action-pypi-publish through trusted publishing, id-token: write as the only credential, attestations on. Environment pypi; a manual run goes to testpypi and skips an existing version
release gh release create with the changelog section as body, --generate-notes appended, sdist and wheel attached. Pre-release tags (v2.2.0rc1) are marked --prerelease and not --latest

A manual run from a tag rehearses the whole path against TestPyPI and stops before the GitHub release. The guard script has tests (tests/test_release_guard.py).

Packaging

  • Python floor 3.12 (requires-python, classifiers, ruff target; 3.14 added to the classifiers). The ecosystem shares one floor; nothing in picblocks needed 3.12. Recorded under Removed.
  • requirements.txt and pytest.ini fold into pyproject.toml, which already carried the dependencies and the web/dev extras; make init and the unit job install .[web,dev], and the CI cache keys on pyproject.toml alone (they still named setup.py, deleted in post-merge cleanup for #3, and v2.1.0 #4). test_make_stats.py now asserts there is no requirements.txt to drift.
  • Repository, Issues and Changelog URLs added. Dependabot gains a pip ecosystem beside the existing actions one.

Security

  • Actions were already SHA-pinned with persist-credentials: false; the new workflows follow the same pattern, contents: read at the top and raised per job only where a job writes.
  • No token stored anywhere — trusted publishing replaces make publish's API token, and each file carries PEP 740 provenance.
  • zizmor --persona=regular reports no findings; actionlint clean.

Tests

  • 72 passed (61 before, plus the guard tests) on Python 3.13 with -m "not live_mcrit"; ruff check, ruff format --check and ty check clean.
  • python -m build + twine check --strict pass; the wheel installs into a clean venv, imports from site-packages, and reports 2.1.0 through importlib.metadata. Metadata reads Requires-Python: >=3.12, License-Expression: BSD-2-Clause.
  • The next release will be the first with a ## [X.Y.Z] - <date> section; until then a tag push fails at the guard with a message saying so.

What a maintainer has to configure once

  1. A trusted publisher on pypi.org for picblocks: owner danielplohmann, repository picblocks, workflow publish-release.yml, environment pypi; the same on test.pypi.org with environment testpypi for rehearsals.
  2. GitHub environments pypi and testpypi. A required reviewer on pypi turns the publish into an approval step.
  3. The no-changelog label.

make publish remains the manual fallback until 1 is done.

Related pull requests across the ecosystem

The same process, one PR per repository. None depends on another to merge; release order once merged is smda → purepdb → picblocks → MCRIT → MCRITweb → docker-mcrit.

…e memory before

Releasing was `make publish` with an API token, there were no GitHub
releases, the release history lived in the README, and nothing checked that
a tag named the version pyproject.toml declares.

Pushing a vX.Y.Z tag now refuses to continue unless the tag matches the
declared version, the version has a changelog section, the commit is on
master and CI passed on it; then builds in isolation, installs the wheel into
a clean environment with the checkout kept off sys.path, publishes to PyPI
through trusted publishing with signed provenance, and creates the GitHub
release from the version's changelog section with the generated contributor
list appended. Pre-release tags are marked as such. A manual run rehearses
against TestPyPI and stops before the release.

The history moves into CHANGELOG.md unchanged, with a Keep a Changelog
section above it. A PR that changes picblocks/ or pyproject.toml has to touch
CHANGELOG.md or carry the no-changelog label. requirements.txt and pytest.ini
fold into pyproject.toml, which already carried the dependencies.

The Python floor moves to 3.12, shared across the MCRIT ecosystem.
@danielplohmann

Copy link
Copy Markdown
Collaborator

Carry the concurrency-group fix into this port before it merges.

This PR adds:

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

A rehearsal (workflow_dispatch on a tag) and the real release (push of that tag) carry the same github.ref, so that group holds both. With cancel-in-progress: false the rehearsal queues behind the real run — which is parked on the pypi reviewer gate, waiting for an approval that the rehearsal was supposed to inform. It never starts.

The fix is one line:

  group: release-${{ github.ref }}-${{ github.event_name }}

Two real publishes of one tag are both push, so they still share a group and still serialise. That is the property the group was added for and it is unaffected.

Fixed upstream in smda danielplohmann/smda#353 and purepdb danielplohmann/purepdb#67. Flagging here so this port does not inherit the shape and need the same fix afterwards.

@danielplohmann

danielplohmann commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

Before this lands, please bring publish-release.yml level with smda's current master, so all four PyPI repos run one workflow:

  1. Milestone gate — the Check the milestone for this tag is finished step in verify and the Close the milestone for this tag step in release, byte-identical to smda/purepdb, plus the issues: permissions they need.
  2. Concurrency group — group: release-${{ github.ref }}-${{ github.event_name }} with the comment from ci: scope the release concurrency group to the trigger danielplohmann/smda#353 (merged today). With the ref alone, a TestPyPI rehearsal queues behind a real run parked on the pypi reviewer gate.

The rest already matches. PYTHON_VERSION can stay as it is here.

You have Write on this repo now, so feel free to move the branch into familiary instead of your fork. master is still PR plus code-owner review.

@r0ny123

r0ny123 commented Sep 24, 2026 •

Copy link
Copy Markdown
Collaborator Author

Moved into familiary as suggested: #6 supersedes this PR. It carries this commit unchanged plus one commit that brings publish-release.yml level with smda master:

  1. The milestone gate: the check step in verify and the close step in release, byte-identical to smda, with issues: read / issues: write.
  2. The concurrency group: release-${{ github.ref }}-${{ github.event_name }}, with the comment from ci: scope the release concurrency group to the trigger danielplohmann/smda#353.

PYTHON_VERSION stays at 3.12. I'll close this one once #6 is picked up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants