Skip to content

Release on a tag, with pyproject.toml as the one place the version lives - #176

Open
r0ny123 wants to merge 8 commits into
familiary:masterfrom
r0ny123:release/modernize-release-workflow
Open

r0ny123 wants to merge 8 commits into
familiary:masterfrom
r0ny123:release/modernize-release-workflow

Conversation

@r0ny123

@r0ny123 r0ny123 commented Sep 12, 2026 •

Copy link
Copy Markdown
Collaborator

On master the version lives in setup.py and is read back out of it with a regex at runtime, the release history is a list in the README, and a release is a version bump and a tag with nothing checking that the two agree. This makes pyproject.toml the one place the version is declared, moves the history into CHANGELOG.md, and makes pushing a vX.Y.Z tag the release: a workflow checks the tag against the version and the changelog, builds and installs the wheel, and creates the GitHub release from the changelog section.

It is one of the pull requests giving the MCRIT ecosystem one release process: the same guard script, the same tag-triggered workflow, the same changelog check, and a RELEASING.md in each repository that states only the values that differ.

Change.

Packaging.

  • pyproject.toml (PEP 621) replaces setup.py, ruff.toml and pytest.ini.
  • Its values are master's: version 1.6.0, requires-python = ">=3.12" (pyproject.toml:14), mcrit>=1.12.0 (pyproject.toml:46), ruff target-version = "py312" (pyproject.toml:82), and classifiers from 3.12 to 3.14. The dependency list is master's requirements.txt, which also carries requests and click, which setup.py lacked.
  • get_mcritweb_version() (mcritweb/views/utility.py:457) reads the version from the checkout's pyproject.toml with tomllib, and falls back to the installed metadata for a wheel. create_app stores it in MCRITWEB_VERSION once (mcritweb/__init__.py:271), and the server page shows that value, as on master (mcritweb/views/administration.py:271, :297).
  • requirements.txt stays, because docker-mcrit installs from it against a tagged checkout. tests/testPackaging.py fails if it differs from [project].dependencies, and tests/testMcritFloor.py (Add admin controls for the three corpus repair jobs #212) now compares the mcrit floor of pyproject.toml and requirements.txt.
  • A dev extra carries the pinned pytest, pytest-cov and ruff; CI and make init install -e ".[dev]".
  • Package data (templates/**, static/**, sql/*.sql) is declared, so a wheel is complete. MCRITweb is still deployed from a checkout and published nowhere: the release workflow builds and installs the wheel only to prove the package is complete, and attaches it to the release.

Changelog.

What pushing vX.Y.Z does (.github/workflows/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 on master, and the CI workflow (test.yml) passed on that commit
build python -m build and twine check --strict, then installs the wheel into a clean venv and checks that the version, templates/base.html, static/css/all.css and sql/create_table_server.sql arrived
release gh release create with the changelog section as the body and --generate-notes appended, sdist and wheel attached; a pre-release tag is marked --prerelease and not made latest

The concurrency group is release-${{ github.ref }}-${{ github.event_name }} (.github/workflows/release.yml:15), as in smda#353 and purepdb#67.

CI. test.yml pins actions/checkout and actions/setup-python to commit SHAs with persist-credentials: false, runs on Python 3.12 to 3.14 as on master, and installs the dev extra. dependabot.yml keeps the action pins current weekly and watches pip monthly.

Docs. AGENTS.md's "Versioning & releases" describes pyproject.toml, CHANGELOG.md, the no-changelog label and the tag-triggered workflow. RELEASING.md describes the process and has a table of the values that differ for MCRITweb: one version location, no package index, the CI workflow the gate reads, no milestones, Python 3.12 to 3.14, mcrit>=1.12.0.

Verification.

  • release_guard.py --tag v1.6.0 on this tree passes and writes out the 1.6.0 section; --tag v1.7.0 is refused: "tag v1.7.0 does not match the packaged version (pyproject.toml = 1.6.0)".
  • A wheel built from this tree is mcritweb-1.6.0-py3-none-any.whl. Its metadata reads Requires-Python: >=3.12 and Requires-Dist: mcrit>=1.12.0, and it holds the three files the build job checks.
  • actionlint is clean, and zizmor --persona=regular reports no findings.

Tests. tests/testPackaging.py keeps requirements.txt and the running version equal to pyproject.toml. tests/testReleaseGuard.py covers the guard script. tests/testPythonFloor.py and tests/testMcritFloor.py read the floors from pyproject.toml. Full suite with Chromium on 65053e0: 2092 passed, 11 skipped, none of them in a file this branch changes; ruff check . clean. Of the tests in the changed files, 16 fail on master's code and two cannot import there (they read get_mcritweb_version); the rest are guards that pass on master too.

What a maintainer configures once. The no-changelog label. There is no index and no secret.

Compatibility.

  • pip install -r requirements.txt keeps working. pip install -e . is equivalent, and pip install -e ".[dev]" adds the tooling. docker-mcrit is unaffected until it chooses to build from pyproject.toml.
  • The floors are master's (Python 3.12 and mcrit 1.12.0, both from 1.6.0), so nothing is dropped here.
  • 1.7.0 is the first release cut by pushing a tag.

Related pull requests across the ecosystem. The same process, one PR per repository. None depends on another to merge. Once merged, the release order is smda, purepdb, picblocks, MCRIT, MCRITweb, docker-mcrit.

The version lived in setup.py and was parsed back out of it with a regex at
runtime; the release history lived in the README; a release was a bump commit
and a tag, with nothing checking that the two agreed; and the test tooling
arrived as a side effect of installing mcrit, which stopped being true in
MCRIT 1.8.0.

Packaging metadata moves to pyproject.toml (PEP 621), which is now the only
place the version is declared - the running version is read from it, falling
back to the installed metadata. ruff.toml and pytest.ini fold into the same
file; requirements.txt stays for deployments installing from a checkout, and
a test keeps it identical to the declared dependencies. The release history
moves into CHANGELOG.md unchanged, with a Keep a Changelog section above it.

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 the sdist and wheel, installs the
wheel into a clean environment to prove the templates, static assets and
schema ship, and creates the GitHub release from the changelog section with
the artifacts attached. Nothing is published to PyPI.

A PR that changes mcritweb/ or pyproject.toml has to touch CHANGELOG.md or
carry the no-changelog label. CI pins its actions to commit SHAs and runs on
Python 3.12 to 3.14; 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

Copy link
Copy Markdown
Collaborator

Reviewed against master now that the three integration branches have landed (41b0a17). The release machinery itself reads well — this is about two things that would change the project's supported-platform surface as a side effect, plus a conflict note.

requires-python drops 3.11, and nothing appears to need that

this PR, pyproject.toml requires-python = ">=3.12"
master, setup.py python_requires=">=3.11"
mcrit (the dependency) requires-python = ">=3.11"

The 3.11 floor on master is deliberate and documented in the comment above it — it is inherited from mcrit's own floor, not from anything in mcritweb's source. I could not find anything in this PR's diff that requires 3.12, so as written this drops 3.11 support without an accompanying reason.

CI goes from four Python versions to one

master's matrix is ["3.11", "3.12", "3.13", "3.14"]; this PR runs python-version: "3.12" alone. Combined with the above, 3.11 would be both undeclared and untested — and 3.13/3.14 would stop being tested too, which is a separate loss.

Why this is easy to miss in review

This PR deletes setup.py, and master modifies it. That is a delete/modify conflict: git flags the path but shows no conflict markers, so "keep the deletion" is the natural resolution and the python_requires=">=3.11" line disappears silently along with the file. Tested locally — merging in either direction conflicts on the same six paths:

setup.py  mcritweb/__init__.py  Makefile  .github/workflows/test.yml  AGENTS.md  README.md

The other five are small (one hunk each; mcritweb/__init__.py is an import line where get_mcritweb_version_from_setup was renamed and get_minhash_matching_label was added alongside it — both sides wanted).

Suggestion

Carry requires-python = ">=3.12" → ">=3.11" and restore the four-version matrix in this PR, unless 3.12 is intended — in which case it is worth saying so in the description, since it drops a supported version rather than reorganising packaging.

Not a blocker on the release-on-a-tag mechanism, which is the actual point of the PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GwSfzAD1ZwEoWY3eWvbYvX

@danielplohmann danielplohmann mentioned this pull request Sep 21, 2026
1.5.0 was released after this branch was written, so master's release
has to be carried into the places this branch moves things to, rather
than merged line by line:

- setup.py stays deleted; pyproject.toml takes its 1.5.0 version, and
  CHANGELOG.md gains a `## [1.5.0] - 2026-09-21` section with the release
  text as it was published in the README - the heading the release guard
  looks for, so the declared version has its section.
- README drops the version history for the CHANGELOG pointer, and keeps
  master's reverse-proxy section.
- `make init` and CI install `.[dev]`; the dev extra now pins pytest and
  pytest-cov as well as ruff, the versions master's CI pinned.

One decision this branch made is not kept: raising the floor to Python
3.12. Master (familiary#166) declared >=3.11 in 1.5.0 on purpose - inherited from
mcrit, whose own floor is still >=3.11 on main and in v1.9.0, so the
"shared across the MCRIT ecosystem" rationale does not hold yet. The
floor stays >=3.11 in pyproject.toml (with familiary#166's reasoning), ruff
targets py311, CI runs 3.11-3.14 again, and the [Unreleased] entry that
announced the removal is gone. Moving to 3.12 is its own decision.

Where git merged cleanly and got it wrong:
- utility.py lost `import re`: this branch dropped it with the regex
  version parsing, and master's QUERY_UPLOAD_JOB_ID (familiary#169) needs it. The
  module did not import - ruff's F821 caught it.
- tests/testPythonFloor.py (master) read setup.py and ruff.toml; it now
  reads pyproject.toml, where both live. Comments and messages in
  data.py, testSubmitMetadata.py and testNoStrayPrints.py that pointed at
  setup.py for the mcrit pin point at pyproject.toml.

998 passed, ruff clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EAW1DRkBwmjZtGzQ5pgDA
r0ny123 added a commit to r0ny123/mcritweb that referenced this pull request Sep 23, 2026
Every branch the familiary session should push now sits on the fork,
one commit on master e4bfa55, with its PR text beside it here: familiary#183,
familiary#188, familiary#193, familiary#199, familiary#200, familiary#206, familiary#207 and the export fix. familiary#193, familiary#199,
familiary#206 and familiary#207 differ from the patches on the status page after an
adversarial review; section 13 says how.

Also records the merge conflicts between open PRs that a reviewer will
meet (the changelog lines and familiary#176, familiary#160's palette, familiary#130, familiary#145), and
corrects the ripgrep sample's size everywhere: 11,598 functions, not
8.5k.
@danielplohmann

Copy link
Copy Markdown
Collaborator

Decision: MCRITweb adopts this release process, before 1.7.0, and 1.7.0 will be the test drive: the first release cut by pushing a tag. Could you bring the branch up to date? Please do it once batch C has landed (#298, then #299), since both touch the same files. A few things to carry over, because master has moved since 09-23:

  1. Pins and floor, from master, not from this branch. Master is now Python >=3.12 and mcrit>=1.12.0 (Raise the Python floor to 3.12, following mcrit 1.10.0 #242, Integrate #221, #238, #222, #239: batch lookups and bounded queue reads (mcrit >= 1.12) #248), and CI runs 3.12–3.14. This branch still says requires-python = ">=3.11", mcrit>=1.5.3 and a 3.11–3.14 matrix, so a straight merge would lower both floors. pyproject.toml, requirements.txt, the matrix and tests/testPythonFloor.py / tests/testMcritFloor.py (Add admin controls for the three corpus repair jobs #212) should all agree with master.
  2. setup.py is deleted here and modified on master. That conflict has no markers, so "keep the deletion" silently drops master's pins along with the file. Re-derive pyproject.toml from master's setup.py / requirements.txt rather than resolving the conflict.
  3. The concurrency group from the 09-17 comment is still release-${{ github.ref }}; please make it release-${{ github.ref }}-${{ github.event_name }}, as smda#353 and purepdb#67 did.
  4. Seed CHANGELOG.md [Unreleased] with batch C. Integrate batch C1 (UI): #117 #119 #122 #136 #172 #173 #219 #244, with #297 #298 and Integrate batch C2 (UI): #132 #147 #148 #214 #159 #213 #226 #145 #229 #142 #115 #174 #212 (stacked on #298) #299 list their changes and their "For deployment" notes, and Add admin controls for the three corpus repair jobs #212's changelog line was deferred to this on purpose. With that, 1.7.0's section is ready when the tag goes out.
  5. AGENTS.md "Versioning & releases" still describes setup.py, the regex and bump X.Y.Z. It needs to describe pyproject.toml, CHANGELOG.md, the no-changelog label and the tag-triggered workflow, and RELEASING.md should state the values that differ for MCRITweb.

Today it conflicts in AGENTS.md, README.md, mcritweb/__init__.py, mcritweb/views/administration.py, mcritweb/views/utility.py, ruff.toml, setup.py, tests/testPythonFloor.py and tests/testSubmitMetadata.py, measured against #299's branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UCjRSPdSunUm9rFRrQqGsG

setup.py is deleted here and changed on master, a conflict without markers, so
pyproject.toml takes master's values rather than the branch's: version 1.6.0,
requires-python >=3.12, mcrit>=1.12.0, ruff target py312, and no 3.11
classifier. ruff.toml goes the same way into [tool.ruff].

master's admin pages read the version from MCRITWEB_VERSION, which create_app
fills once; that is kept, and create_app now fills it from
get_mcritweb_version(). testMcritFloor (familiary#212) reads pyproject.toml, and the
manual's traversal test asks for a file that still exists.

README's 1.6.0 entry moves into CHANGELOG.md as its own section, as 1.5.0 did,
and the compare links at the foot point at the current tags.
The workflow runs only on a pushed tag today, so this changes nothing yet.
It keeps the group the same as in smda (#353) and purepdb (#67): there, a
rehearsal started by hand on a tag shared github.ref with the tag's push
run, and with cancel-in-progress off it queued behind it and never
started. Two pushes of one tag still share a group and run one after the
other.
…alues

AGENTS.md's Versioning & releases now says where the version lives and how
it reaches the server page, when a PR needs a changelog entry and what the
no-changelog label and changelog.yml do, and that pushing the tag is the
release. The ruff and pytest settings are pointed at pyproject.toml, where
they moved.

RELEASING.md gets a table of what differs from the other MCRIT
repositories (one version location, no package index, the CI workflow the
gate reads, no milestones, Python 3.12 to 3.14, mcrit>=1.12.0) and a short
section on the Python floor. The sentence about a tag having to match
"every one of them" came from a repository with several version
locations; here there is one.
The entries for familiary#298 and familiary#299, from their change lists and their notes
for deployment, and familiary#212's entry, which was held back for this. familiary#212's
floor change is not repeated: master's mcrit>=1.12.0 was already in 1.6.0.
Fixes made during the two integrations to code that had not been released
are left out.
…ipping

The suite runs from a checkout, never from an installed wheel, so a missing
pyproject.toml or release_guard.py means one was moved, and a skip would
pass over it. Also drops the trailing spaces three README history entries
carried into CHANGELOG.md.
@r0ny123

r0ny123 commented Oct 20, 2026 •

Copy link
Copy Markdown
Collaborator Author

Thanks. Master (6564602, with both batches) is merged in (1495dac), and the rest is in 187ade7, 0b8bd9e and a091051. 65053e0 makes the packaging and guard tests assert that they run from a source tree instead of skipping when they don't.

  1. Pins and floor. 1495dac. pyproject.toml has master's values: version 1.6.0, requires-python = ">=3.12", mcrit>=1.12.0, ruff py312, and no 3.11 classifier. requirements.txt is master's list, and the matrix is master's 3.12 to 3.14. tests/testMcritFloor.py now compares pyproject.toml with requirements.txt, and tests/testPythonFloor.py reads both floors from pyproject.toml; both pass.
  2. setup.py. 1495dac. Deleted, with pyproject.toml rebuilt from master's setup.py and requirements.txt rather than taken from the branch. A wheel built from the merge reads Version: 1.6.0, Requires-Python: >=3.12 and Requires-Dist: mcrit>=1.12.0. Nothing reads setup.py any more:
    • create_app fills MCRITWEB_VERSION from get_mcritweb_version() (mcritweb/__init__.py:271), and the server page keeps master's read of that config value (mcritweb/views/administration.py:271, :297);
    • the manual's traversal test asks for pyproject.toml, so it still names a real file;
    • master's 1.6.0 README entry is a ## [1.6.0] - 2026-10-16 section of CHANGELOG.md, so release_guard.py --tag v1.6.0 passes on this tree.
  3. Concurrency. 187ade7: release-${{ github.ref }}-${{ github.event_name }}. The workflow runs only on a pushed tag here, so this keeps the shape the same as smda and purepdb rather than fixing a queue it can hit today.
  4. Changelog. a091051. [Unreleased] lists batch C, from the tables of Integrate batch C1 (UI): #117 #119 #122 #136 #172 #173 #219 #244, with #297 #298 and Integrate batch C2 (UI): #132 #147 #148 #214 #159 #213 #226 #145 #229 #142 #115 #174 #212 (stacked on #298) #299, with their "For deployment" notes as Upgrading lines (Show who requested a job (#37) #172, Rename a function from its page (#72) #173, Bound the result cache and write cached reports as compact JSON #229), and Add admin controls for the three corpus repair jobs #212's entry. Fixes made during the integrations to code that was never released are left out. Add admin controls for the three corpus repair jobs #212's floor change is not repeated, because 1.6.0 already carried mcrit>=1.12.0.
  5. AGENTS.md and RELEASING.md. 0b8bd9e.
    • "Versioning & releases" describes pyproject.toml, CHANGELOG.md, the no-changelog label and changelog.yml, and the tag as the release. The ruff and pytest references point at pyproject.toml.
    • RELEASING.md has a table of what differs for MCRITweb: one version location, no package index, test.yml as the CI gate, no milestones, Python 3.12 to 3.14, mcrit>=1.12.0.
    • The template sentence about the tag matching "every one of them" is gone, since there is one version location here.

actionlint is clean and zizmor --persona=regular reports no findings. Full suite with Chromium on 65053e0: 2092 passed, 11 skipped, none in a file this branch changes; ruff check . clean. The description is updated to match.

master's three unreleased README entries move into CHANGELOG.md's
Unreleased section, text unchanged: the WAL change under Changed, the
atomic secret key under Fixed, and the jQuery UI update under a new
Security heading. The WAL entry's "above" now names README.md, where
the "SQLite database" section stays.
@r0ny123

r0ny123 commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator Author

Master (fe6b313) is merged in, in 9706f84. This PR replaces README's Version History with a link to CHANGELOG.md, so master's three new unreleased README lines moved into CHANGELOG.md's Unreleased section, with their text unchanged:

  • WAL mode under Changed. Its "see above" now points to README.md, where the "SQLite database" section stays.
  • The atomic secret key under Fixed.
  • jQuery UI 1.13.3 under a new Security heading.

502 tests pass across the changed and related modules.

r0ny123 added a commit that referenced this pull request Oct 25, 2026
#176 installs CI's tools from the dev extra, so rjsmin is pinned there rather than in the
workflow. AGENTS.md keeps #267's and #310's bullets with the minified build's dropzone bullet.
r0ny123 added a commit that referenced this pull request Oct 25, 2026
#176 installs CI's tools from the dev extra, so rjsmin is pinned there rather than in the
workflow. AGENTS.md keeps the bullets #291, #292 and #317 added, with the minified build's
dropzone bullet.
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