Skip to content

ci(ci): release on a tag, with the checks that were memory before - #343

Merged
danielplohmann merged 6 commits into
danielplohmann:masterfrom
r0ny123:ci/release-workflow
Sep 14, 2026
Merged

danielplohmann merged 6 commits into
danielplohmann:masterfrom
r0ny123:ci/release-workflow

Conversation

@r0ny123

@r0ny123 r0ny123 commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Releasing today is make package then make publish with an API token, and every check around it lives in the head of whoever is doing it. #341 and #337 wrote those checks down; this makes them run.

Pushing a vX.Y.Z tag builds, publishes, creates the release and closes the milestone. Nothing else is triggered by a branch push, so a release stays a deliberate act.

What it refuses to publish

Five gates, each of which is a mistake that is only visible afterwards — and a version yanked from PyPI stays unusable under that number forever:

gate the mistake it catches
tag matches both version strings the three-place bump with one place missed; the tag is the only thing a user sees
the version has a CHANGELOG.md section ## [Unreleased] renamed without being written, or not renamed at all
the commit is an ancestor of master a release cut from a branch
CI concluded success for that commit "tag after master is green" as a gate rather than a habit
the milestone named for the tag has no open items #341's scope rule, enforced — a release cut with work still assigned to it

There is already a v4.7.0 milestone with two open items, so this gate is live rather than theoretical.

What it does differently from the Makefile

Trusted publishing, not a token. id-token: write and no username or password, per the action's own README — so there is no secret to leak, rotate or forget to scope, and each file carries signed PEP 740 provenance.

The build is isolated, unlike make package's --no-isolation, so the wheel is a product of the declared build requirements rather than of whatever the machine held.

The artifact is tested, not the tree it came from. Before anything is published the wheel goes into a clean environment carrying only the declared runtime dependencies, and disassembles a bundled sample with it. A missing module, absent package data or a dependency that only the development environment supplies fails there rather than on a user's machine. I found the shape of that check the useful way: running the full suite against the installed wheel fails, because a test imports a CI helper that needs tqdm — which is exactly the kind of dev-environment dependency this is meant to catch.

Release notes

The body is this version's changelog section; --generate-notes appends the merged pull requests, contributors and compare link underneath, since the API pre-pends a supplied body rather than replacing it. The entry says what changed and what it cost; the generated half says who did it and where to diff it, and neither substitutes for the other.

.github/release.yml puts the dependency bumps in their own group — 12 of the last 100 merged PRs are Dependabot's, and the repo already labels them, so otherwise they sit between the real changes.

Verification

The parts that parse anything are in .github/workflows/scripts/release_guard.py with 12 tests, because the changelog shape they read is a convention and a convention with no test drifts until the release that needs it finds out. Each test verified to fail under a mutation of the line it covers: the section not stopping at the next heading, the heading date not required, an empty section accepted, a version disagreement ignored, the v prefix not required.

Everything I could exercise without a release, I did:

  • the smoke step extracted from the YAML and run verbatim — the heredoc survives the block scalar and prints smda 4.6.0: 33 functions, status ok
  • the milestone gate run verbatim against this repo, in all three branches: no milestone, open items (fails), 100% (passes)
  • gh release create accepts --notes-file and --generate-notes together — it reaches the API rather than rejecting the combination
  • repository-url: '' resolves to PyPI: the canonical input carries no default, so the action falls through to the deprecated alias that defaults to the real index
  • zizmor --persona=regular clean. It flagged softprops/action-gh-release as superfluous and exited 11, which would have failed the Workflow audit job — replaced with the runner's own gh, which also means one fewer third party in the path that signs and announces a release

Full suite 2,151 passed, 1 skipped, 2,596 subtests; ruff clean; make typecheck exit 0 at 267, master's own count, so the new script adds none.

The one thing that cannot be automated

Trusted publishing needs the publisher configured on PyPI before the first run, and the workflow names two environments:

environment publisher on workflow
pypi pypi.org → smda → Publishing release.yml
testpypi test.pypi.org release.yml

Worth adding a required reviewer on pypi — that turns the publish into an approval step, which is the last chance to stop a release after everything else has passed.

Rehearse before trusting it: run the workflow manually from a tag. It takes the same five gates and publishes to TestPyPI, then stops without creating a release. skip-existing is on for that path only, so a second rehearsal of the same tag is not blocked by the first; on PyPI a collision means the version is already public and stopping is correct.

Closes nothing on its own — it is #323's rollout step 4, and it makes #341's "close it when the tag is pushed" automatic.

Update: the ecosystem-wide shape

The second commit brings this workflow to the shape now shared by purepdb, mcrit, mcritweb, mcrit-plugin and docker-mcrit — the same guard over the same changelog convention, the same gates, the same changelog check, and a RELEASING.md in each repository stating only the values that differ. What changed here as a result:

  • Pre-releases. The guard accepts a PEP 440 pre-release tag (v4.7.0rc1) and reports it, so the GitHub release is marked as a pre-release and never becomes latest; PyPI does not install one without --pre. It accepts a changelog heading with or without the v prefix, since the other repositories write [1.9.0] and this one wrote [v4.6.0].
  • The wheel smoke test runs with python -P, so the checkout in the working directory cannot stand in for the wheel. This repository's src layout hid that; running the same step in a flat-layout repository imported the source tree and passed on a wheel that was never checked.
  • The changelog check exempts Dependabot and also covers pyproject.toml.
  • SmdaConfig.VERSION is read from smda.__version__ rather than kept in sync by hand, so the version is declared once, the guard reads one place, and a release bumps one line. report.smda_version is unchanged.
  • pyproject.toml declares the license as the SPDX expression BSD-2-Clause with license-files (PEP 639) in place of the free-text form and the deprecated classifier — the wheel now carries License-Expression: BSD-2-Clause — and gains Repository, Issues and Changelog URLs. Building needs setuptools>=77; the wheel requirement was already unnecessary.
  • Python floor: stays at 3.11, with the policy for moving it written down instead — see the update below.
  • RELEASING.md documents cutting, rehearsing, pre-releases, recovery and the one-time configuration; AGENTS.md points at it and no longer describes a three-place bump.

Re-verified on the second commit: full suite 2,151 passed, 1 skipped (make test-all), ruff clean, make typecheck at master's own 267; python -m build + twine check --strict pass and the wheel, installed into a clean Python 3.13 venv with -P, disassembles cutwail_xored to 33 functions with SmdaConfig.VERSION == smda.__version__ == 4.6.0; zizmor --persona=regular and actionlint clean.

Update: the 3.11 floor is kept

An earlier revision raised the floor to 3.12 for ecosystem alignment. It is back at 3.11, because the premise did not hold yet: no dependency needs 3.12, MCRIT and purepdb still declare 3.11, and raising SMDA's floor alone would have left it the only component at 3.12 — with pip on 3.11 silently resolving MCRIT's unbounded smda>=4.2.13 back to 4.7.0 while MCRIT kept advertising 3.11.

Reverted: requires-python, the 3.11 classifier, ruff's target-version, the ci.yml matrix with its Windows and macOS legs and the coverage conditions keyed to them, the MCRIT install legs, and the interpreter the profile, security, benchmark and release workflows pin. The release workflow builds and smoke-tests on 3.11, since an installed wheel is only proven on the oldest interpreter it claims.

Kept: the PEP 639 licence expression and license-files, setuptools>=77 without wheel, and the project URLs.

In place of the bump, a written policy in RELEASING.md and a Deprecated notice under Unreleased: SMDA's floor follows MCRIT's and moves in the same wave, at whichever comes first of MCRIT and purepdb moving to 3.12, a runtime dependency dropping 3.11, or 3.11's end of life in October 2027.

Verified on the current head: full suite 2,168 passed, 1 skipped, 2,601 subtests; ruff clean at target-version = "py311"; make typecheck exit 0; zizmor clean. A real python -m build produces a wheel whose metadata reads Requires-Python: >=3.11, License-Expression: BSD-2-Clause and License-File: LICENSE with 3.11–3.14 classifiers, and twine check --strict passes both files. The release script and its tests were written under the 3.12 floor, so I checked they hold on 3.11: ruff at py311 reports syntax a version cannot parse and finds none, and all three changed Python files compile under 3.9.

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.

@r0ny123

r0ny123 commented Sep 11, 2026

Copy link
Copy Markdown
Contributor Author

Renamed the workflow — two files called release.yml read as a duplicate in a diff even though they are unrelated.

Only one of the names was ever mine to choose. .github/release.yml is a fixed path: GitHub reads the generated-notes configuration from there and nowhere else. The workflow's filename is free, so that is the one that moved:

.github/release.yml configures the notes GitHub generates. Not a workflow.
.github/workflows/publish-release.yml the workflow. name: Publish release.

Each now names the other in its header, so the next reader does not have to work out why there were two.

No behaviour change: nothing referenced the workflow by filename except the AGENTS.md line added here, zizmor is still clean, and the suite is 2,151 passed, 1 skipped, 2,596 subtests with ruff clean and make typecheck at master's own 267.

Releasing is `make package` then `make publish` with an API token, and
every check around it lives in whoever is doing it: that the tag matches
the packaged version, that the version has a changelog section, that the
commit is on master, that CI went green on it, that the milestone is
finished. None of that is visible afterwards, and a version yanked from
PyPI stays unusable under that number forever.

Pushing a vX.Y.Z tag now runs all five as gates, builds, publishes and
closes the milestone.

Trusted publishing rather than a token, so there is no secret to leak,
rotate or forget to scope, and each file carries signed provenance. The
build runs isolated, unlike `make package --no-isolation`, so the wheel is
a product of the declared build requirements rather than of the machine.

Before anything is published the wheel is installed into a clean
environment carrying only the declared runtime dependencies and used to
disassemble a bundled sample. A missing module, absent package data or a
dependency only the development environment supplies fails there rather
than on a user's machine -- the artifact is tested, not the tree it came
from.

The release notes are this version's changelog section with GitHub's
generated list appended under it; the API pre-pends a supplied body rather
than replacing it. The entry says what changed and what it cost, the
generated half says who did it and where to diff it. `.github/release.yml`
groups the dependency bumps so they do not sit between the real changes.
That file is named by GitHub, which reads the configuration from that path
and nowhere else, so the workflow is named apart from it rather than being
a second release.yml.

The checks that parse anything live in a script with tests, because the
changelog shape they read is a convention and a convention with no test
drifts until the release that needs it finds out.

A manual run from a tag rehearses the whole path against TestPyPI and
stops before the GitHub release.
@r0ny123
r0ny123 force-pushed the ci/release-workflow branch from 4049d12 to 92926da Compare September 11, 2026 18:00
@r0ny123

r0ny123 commented Sep 11, 2026

Copy link
Copy Markdown
Contributor Author

Cut the comments back to what the code cannot say, and squashed — the intermediate states were "comments added, then removed" and a rename, neither of which is worth a reviewer's time.

AGENTS.md says no comments in code unless asked, and I had written 40 lines of them into the workflow. Most were either restating the line below or carrying rationale that belongs in the commit body, which is where it now is. Nine survive, and each is behaviour a reader cannot see from the code:

  • repository-url: '' resolves to PyPI. The canonical input carries no default, so the action falls through to its deprecated alias, which defaults to the real index. Without this noted, it reads like a bug and gets "fixed".
  • --generate-notes appends under --notes-file rather than replacing it — the ordering the whole notes design rests on.
  • skip-existing only for a rehearsal, because a collision on PyPI means the version is already public and stopping is correct.
  • cancel-in-progress: false — a cancelled publish can leave PyPI holding some files of a version and not others.
  • id-token: write is mandatory for trusted publishing and must be the only credential in the job.
  • .github/release.yml is not a workflow — GitHub reads that configuration from that path and nowhere else, which is also why the workflow is named apart from it.

The rest went to the commit body.

Verified it is a comment-only change rather than trusting the diff: both YAML files parse identically to the reviewed version, and every remaining changed line is inside a comment or a docstring. The smoke step was re-extracted from the trimmed YAML and run again — the heredoc still survives the block scalar and still prints smda 4.6.0: 33 functions, status ok.

Suite 2,151 passed, 1 skipped, 2,596 subtests; ruff clean; make typecheck at master's 267; zizmor clean across all workflows.

The release workflow was written for this repository alone. purepdb, mcrit,
mcritweb, mcrit-plugin and docker-mcrit now carry the same shape - a guard
script over the same changelog convention, a tag-triggered workflow with the
same gates, a changelog check on every PR, and a RELEASING.md stating the
repository-specific values - so a maintainer learns one process. This
commit brings smda's copy to that shape.

The guard accepts a PEP 440 pre-release tag (v4.7.0rc1) and reports it, so
the GitHub release is marked as a pre-release and never becomes latest; it
accepts a changelog heading with or without the v prefix, since the other
repositories write [1.9.0] and this one wrote [v4.6.0]. The wheel smoke test
runs with -P so the checkout cannot stand in for the wheel; this repository's
src layout hid that, a flat layout does not. The changelog check exempts
Dependabot and covers pyproject.toml.

SmdaConfig.VERSION is read from smda.__version__ rather than kept in sync by
hand, so the version is declared once and a release bumps one line. The
license is declared as an SPDX expression with license-files (PEP 639) in
place of the free-text form and the deprecated classifier, and the project
URLs gain Repository, Issues and Changelog.

The Python floor moves to 3.12, shared across the ecosystem; the interpreter
matrices and the tool target follow.
…-release-workflow

# Conflicts:
#	CHANGELOG.md
@danielplohmann danielplohmann mentioned this pull request Sep 13, 2026
…-release-workflow

# Conflicts:
#	CHANGELOG.md
#	src/smda/SmdaConfig.py
@r0ny123

r0ny123 commented Sep 13, 2026

Copy link
Copy Markdown
Contributor Author

Merged v4.7.0 in. One thing about how, since the obvious resolution would have written a false entry into the release you just cut.

The bump moved every Unreleased bullet under ## [v4.7.0] - 2026-09-13 and opened a fresh empty Unreleased. Git showed one conflict block — this PR's Removed bullet — but silently auto-merged the other three of this PR's four bullets into the dated v4.7.0 section, by context, with no marker. Resolving only the visible block would have left the 4.7.0 entry claiming this release workflow, the 3.12 floor and the licence change had shipped in 4.7.0.

So the changelog is master's verbatim with this PR's four bullets placed explicitly in the new Unreleased, and checked rather than eyeballed: all four (#343) bullets sit under ## [Unreleased], and the diff against master removes nothing, so your v4.7.0 section is byte-identical to what you released.

SmdaConfig.py resolved to this PR's side: the bump re-set the literal to "4.7.0", this PR replaces the literal with __version__, and __init__.py already reads 4.7.0 — so SmdaConfig.VERSION resolves to 4.7.0 with no second copy to keep in sync.

A useful side effect: run against the merged tree, release_guard.py --tag v4.7.0 accepts your release — the version matches and it finds the real dated section. The first release the workflow will actually see is the one after this, but it already agrees with the one you cut by hand.

Suite 2,168 passed, 1 skipped, 2,601 subtests; ruff clean; make typecheck exit 0; zizmor clean.

@danielplohmann

Copy link
Copy Markdown
Owner

Reviewed against the source rather than the body, on a worktree at 0108f9a (which already carries this morning's 6517d88). The guard is the right shape and the tests are where they need to be — that script runs once per release, minutes before the artifact becomes permanent, and it is the only part of this that can be exercised beforehand.

Verified here

  • The guard against the real tree, for the tag that just shipped. release_guard.py --tag v4.7.0 passes, writes version=4.7.0 prerelease=false, and extracts exactly the v4.7.0 section — 74 lines, opening at ### Changed and stopping before ## Older releases, with nothing from the format documentation above it or the older entries below. That is the check I most wanted to see on a file this one is, since the convention it reads was only written down two days ago.
  • The 12 tests: 12 passed, 5 subtests in 0.05s.
  • SmdaConfig.VERSION is smda.__version__ is literally true, and there is no import cycle — smda/__init__.py imports logging and nothing else.
  • The single VERSION_SOURCES entry is complete, which I checked rather than assumed: pyproject.toml already carried dynamic = ["version"] with version = {attr = "smda.__version__"}, so after this PR there is exactly one literal and the guard reads it.
  • LICENSE exists, so license-files = ["LICENSE"] resolves; the matrices are consistent at 3.12/3.13/3.14 with Windows and macOS on the floor, and the five MCRIT install legs match.
  • Independently, the v4.7.0 wheel now on PyPI installed into a clean venv and run with python -P gives 33 functions, status ok — the same figure your smoke step asserts, on the artifact rather than the tree.

Five things, none of them blocking

  1. RELEASING.md claims a step the workflow does not run. Its build description ends "...to disassemble a bundled sample with it and run the smda entry point". The smoke step disassembles the sample and stops there — and this package declares no [project.scripts] at all, so there is no smda entry point to run. It reads like a line that is true in a repository that has console scripts. Drop the clause here, or add the entry point to the smoke step in the repository that has one.

  2. The CI gate is narrower than "master is green". It requires a successful ci.yml run for the commit, but master also runs Fuzzing, Security and the Performance & Correctness Benchmark, and the benchmark is the one that would catch a recovery regression. I am not asking for it in the gate — it reports skipping on some events, and a gate that can never complete is worse than one that is narrow — but RELEASING.md should say that "CI passed" means ci.yml specifically, so nobody reads the gate as covering the benchmark.

  3. The first rehearsal needs a tag that does not exist yet. workflow_dispatch runs the workflow file from the ref it is given, so a rehearsal against v4.7.0 or anything older finds no workflow there. In practice the first one has to be a throwaway pre-release tag cut after this merges. One sentence in the Rehearsing section saves somebody ten confused minutes.

  4. Two heading forms are now in play. AGENTS.md and RELEASING.md both say to write ## [X.Y.Z] - YYYY-MM-DD, while the file itself carries ## [v4.7.0] - 2026-09-13 and the anchor [v4.7.0]: at the foot. The guard accepts both deliberately, which is right for an ecosystem where the other repositories write [1.9.0] — but within this file it would be better to pick one and have the docs say the one that is there. Either is fine; the docs currently describe the form the file does not use.

  5. The 3.11 floor, which is the only part I would call a product decision rather than a review note. Nothing in the engine needs 3.12, so this is ecosystem alignment, and the cost falls outside this repository: smda.ida is installed into whatever interpreter IDA bundles, and a user whose IDA runs 3.11 stops at 4.7.0 for good. If the supported IDA line ships 3.12 or newer this is free and worth saying so in the entry; if it does not, the Removed entry should say who it costs. Not mine to settle — flagging it for @danielplohmann, since it is a support-policy call rather than a packaging one.

One observation rather than a request: none of publish-release.yml itself runs until a tag is pushed, so the YAML around the tested script is exercised for the first time by a real release. That is what the TestPyPI rehearsal is for, and it is why I would rehearse before the next tag rather than after any change to the workflow.

🤖 Generated with Claude Code

RELEASING.md said the build ran the `smda` entry point. This package
declares no console scripts, so there is none; the smoke step
disassembles a sample and stops there.

"CI passed" read as covering all of master's checks. The gate reads
ci.yml only -- fuzzing, the security audit and the benchmark are not in
it, the benchmark because it reports skipping on some events and a gate
that can never complete is worse than a narrow one. Say so, and name the
benchmark as the one to confirm by eye, since it is the one that catches
a recovery regression.

A manual rehearsal runs the workflow as it exists at the chosen tag, so no
tag cut before this workflow has one to run. Say that the first rehearsal
needs a fresh tag.

The docs described `## [X.Y.Z]` headings while the file uses
`## [vX.Y.Z]`. Aligned them to the file. The guard accepts both on
purpose, since other repositories sharing it write the bare form, so its
error message now names both rather than steering toward the one this
file does not use.

State what the 3.12 floor costs rather than calling it alignment. IDA 9.3
and 9.4 accept any Python from 3.8 through idapyswitch, so an IDA pointed
at 3.8-3.11 has to be switched to 3.12 or newer before smda.ida can be
installed into it from this release on.
@r0ny123

r0ny123 commented Sep 13, 2026

Copy link
Copy Markdown
Contributor Author

All five taken in 6715097, and thanks for checking the published v4.7.0 wheel directly — an independent 33 functions, status ok on the artifact is a better confirmation than anything the tree can give.

1. The entry point. Dropped. Right that it was a line true in a repository with console scripts; this one declares none.

2. Which CI. RELEASING.md now says the gate reads ci.yml only, and names fuzzing, the security audit and the benchmark as not covered — with your reason for leaving them out, and the benchmark called out as the one to confirm by eye before tagging, since it is the one that catches a recovery regression.

3. The first rehearsal. Added to Rehearsing: a manual run uses the workflow file as it exists at the chosen tag, so the first rehearsal needs a tag cut after this merges — a throwaway vX.Y.Zrc0 is enough.

4. Heading forms. Aligned the docs to the file: RELEASING.md and AGENTS.md now say ## [vX.Y.Z], including the pre-release form. The sweep turned up one more of the same kind that you did not list — the guard's own error text told a user to write ## [4.8.0], the form this file does not use. Since the script is shared and other repositories write the bare form, it now names both rather than switching, which keeps it right everywhere it runs.

5. The 3.11 floor. I checked rather than guessed, against IDA itself. Both 9.3 and 9.4 ship idapyswitch, whose help says "the minimum supported version is Python 3.8", so IDAPython is linked to whichever Python 3 the user selects rather than to a bundled one.

So the floor is not free, but the cost is narrower than stopping at 4.7.0 for good: an IDA pointed at 3.8–3.11 has to be switched to a 3.12-or-newer Python before smda.ida can be installed into it. That is a one-command change where a newer Python is available, and a real barrier on a locked-down image pinned to an older one. The Removed entry now says exactly that.

The floor itself is unchanged — whether that cost is worth ecosystem alignment is the support-policy call you flagged, and it is yours.

Suite 2,168 passed, 1 skipped, 2,601 subtests; ruff clean; make typecheck exit 0; zizmor clean; and the guard still accepts v4.7.0 against the real tree.

Agreed on the closing observation — the YAML around the script first runs on a real release, so the rehearsal belongs before the next tag.

@danielplohmann

Copy link
Copy Markdown
Owner

Answering the 3.11 floor, since it is the one thing I left open — and thanks for going to idapyswitch rather than guessing at it, which changed the shape of the question.

Keep 3.11 for now. Not because the long-term argument is wrong, but because the premise the entry rests on is not true yet, and the cost of waiting is one CI leg.

What I checked

  • No dependency needs 3.12. purepdb and pycxxfilt are >=3.11; lief >=3.9, capstone >=3.8, dnfile >=3.8, dncil >=3.7.
  • 3.11 is exercised, not merely claimed. master's matrix runs 3.11 through 3.14 on Linux with Windows and macOS on the floor, and ubuntu + 3.11 is the leg that carries coverage and diff-coverage. So there is no 3.12-only syntax in the tree to be accommodated.
  • The ecosystem floor is 3.11, not 3.12. mcrit is requires-python = ">=3.11" and classifies 3.11; purepdb the same. The Removed bullet's "the MCRIT ecosystem now shares a 3.12 floor so one interpreter serves every component" describes a state that does not exist yet — after this PR smda would be the only component at 3.12.
  • Moving alone breaks mcrit quietly. mcrit depends on smda>=4.2.13 with no upper bound while declaring 3.11. Ship a 3.12-only smda and pip on 3.11 silently resolves smda back to 4.7.0 — mcrit keeps advertising 3.11 while its engine is frozen, and nothing errors. That is the failure shape Generate GitHub releases from the changelog section, starting with smda #342 was written to design against.

On the long-term argument

Your case is that the switch is paid once and is better paid deliberately than under pressure. I agree with that, and it is why I want the policy written down rather than the floor left to drift. The timing does not follow from it, though:

  1. The cost of bumping does not grow while we wait. It is one line plus matrix legs, and this repository shipped four releases in three weeks — every release between now and 3.11's EOL in October 2027 can carry it. There is no window to catch.
  2. The population that pays shrinks while we wait. The EOL is itself what moves distributions and IDA images along. Someone pinned to 3.11 today has thirteen months of their own vendor pushing them forward; bumping now hits that person, bumping on a trigger hits fewer of them for the same benefit.
  3. For the person it actually costs, it is not "once". Your own finding is that idapyswitch makes it one command where a newer Python is available. On a locked-down image it is a stop until somebody re-images, and "ecosystem alignment, a year early" is a hard reason to hand them. "lief dropped 3.11" is an easy one.

One mechanical note on reversibility: UP is in the ruff select list and those rules are gated on target-version, so py312 brings UP040 and UP046/047 live, at which point the floor stops being metadata and becomes syntax. Nothing would be rewritten today — src/ has no TypeAlias, TypeVar or Generic[ — but that is how "we can always revert" stops being true without anyone deciding it.

What I would like in this PR

Drop the floor, keep everything else. To be specific about the hunks:

Out: requires-python = ">=3.12" and the dropped 3.11 classifier; ruff target-version = "py312"; the ci.yml python-version changes (the matrix, the Windows and macOS legs, and the four if: conditions keyed to the coverage leg); the MCRIT install matrix legs; and the fourth Removed bullet with its IDA paragraph.

In, unchanged: PEP 639 (license = "BSD-2-Clause" with license-files, setuptools>=77, dropping wheel), the Repository/Issues/Changelog URLs, and the build bullet that describes them. None of it depends on the floor.

And in place of the bump, a policy

Since what you are after is predictability, let us have it in writing rather than as a floor set early:

  • smda's floor follows mcrit's, and the two move in the same release wave.
  • The trigger is whichever comes first: mcrit and purepdb move to 3.12, a runtime dependency drops 3.11, or 3.11 reaches EOL in October 2027.
  • Say it publicly now — a supported-Pythons line in RELEASING.md and a note in the next release — so smda.ida users get thirteen months of warning rather than discovering it as a silent pip downgrade.

Either in this PR or a follow-up, whichever keeps this one moving. Everything else here I am ready to merge.

🤖 Generated with Claude Code

No dependency needs 3.12 -- purepdb and pycxxfilt are >=3.11, lief >=3.9,
capstone and dnfile >=3.8, dncil >=3.7 -- and MCRIT and purepdb still
declare 3.11. Raising SMDA's floor alone would not have aligned anything:
it would have left SMDA the only component at 3.12, and pip on 3.11 would
silently resolve MCRIT's unbounded smda>=4.2.13 back to 4.7.0 while MCRIT
kept advertising 3.11 and nothing errored.

So the floor goes back to 3.11: requires-python, the 3.11 classifier,
ruff's target-version, the ci.yml matrix with its Windows and macOS legs
and the coverage conditions keyed to them, the MCRIT install legs, and
the interpreter the profile, security and benchmark workflows pin. The
release workflow now builds and smoke-tests on 3.11 too, since the
installed wheel is only proven on the oldest interpreter it claims.

Everything else stays: the PEP 639 licence expression and license-files,
setuptools>=77 without wheel, and the project URLs.

In place of the bump, the policy. SMDA's floor follows MCRIT's and moves
in the same wave, triggered by whichever comes first of MCRIT and purepdb
moving to 3.12, a runtime dependency dropping 3.11, or 3.11's end of life
in October 2027. RELEASING.md states it and Unreleased carries the
deprecation notice, so smda.ida users get the warning in advance rather
than meeting it as a silent downgrade.

The release script and its tests were written while the floor was 3.12.
Checked they hold on 3.11: ruff passes with target-version py311, which
reports syntax a version cannot parse, and all three changed Python files
compile under 3.9, a stricter lower bound.
@r0ny123

r0ny123 commented Sep 14, 2026

Copy link
Copy Markdown
Contributor Author

Done in 466cf71 — floor dropped, everything else kept, and the policy in writing. Your mcrit argument settles it: a 3.12-only smda under mcrit's unbounded smda>=4.2.13 would resolve silently to 4.7.0 on 3.11, which is exactly the failure this PR exists to design out.

Out, per your list: requires-python and the 3.11 classifier, ruff's target-version, the ci.yml matrix with its Windows and macOS legs and the four coverage-leg if: conditions, and the MCRIT install legs.

Three hunks you did not list were the same floor in other files, so they went too: the pinned interpreter in profile.yml, security.yml and perf_benchmark.yml, the README.md line, and three AGENTS.md lines that said 3.12+. And the release workflow's own interpreter, which matters more than it looks: the smoke step installs the wheel and runs it, so on 3.12 it would not catch a 3.11 incompatibility in the artifact. It builds and smoke-tests on 3.11 now.

Kept, verified in a real build rather than read off the diff: the wheel's metadata carries Requires-Python: >=3.11, License-Expression: BSD-2-Clause and License-File: LICENSE with 3.11–3.14 classifiers, and twine check --strict passes both files. changelog.yml stays as it was too — its Dependabot exemption and pyproject.toml coverage are not about the floor.

The policy is in RELEASING.md under Supported Python versions, with a Deprecated notice under Unreleased: the floor follows MCRIT's and moves in the same wave, at whichever comes first of MCRIT and purepdb moving to 3.12, a runtime dependency dropping 3.11, or end of life. I checked that date against the devguide rather than carrying it — PEP 664, 2027-10, security-only now. Your point about UP rules turning the floor from metadata into syntax is recorded there as well, since it is the reason a later bump is not a one-line revert.

One risk worth closing, since the release script was written while the floor was 3.12: there is no 3.11 on this machine and I did not want to install an interpreter unasked, so I checked two ways instead. ruff at target-version = "py311" reports syntax a version cannot parse and finds none, and all three changed Python files compile under 3.9, a stricter lower bound. CI's restored ubuntu + 3.11 leg is the authoritative run.

Suite 2,168 passed, 1 skipped, 2,601 subtests; make typecheck exit 0; zizmor clean; the guard still accepts v4.7.0. The PR body now says the floor is kept rather than raised.

@danielplohmann

Copy link
Copy Markdown
Owner

Verified 466cf71 on saturn. Everything checks out, including the parts I could only take on trust last time.

The floor revert is complete, and byte-identical where it should be

ci.yml, security.yml, perf_benchmark.yml, profile.yml and README.md no longer appear in the diff against master at all — not reverted approximately, reverted exactly. pyproject.toml is now PEP 639, the four project URLs and setuptools>=77 without wheel, and nothing else: requires-python = ">=3.11" and the 3.11 classifier are back where they were.

The release workflow building on 3.11 is the part I would not have asked for and is the right call. An artifact proven only on 3.12 while its metadata claims 3.11 is a gap the smoke step exists to close, and it would have survived the revert unnoticed.

Wheel metadata, built here rather than read off the diff

python -m build then twine check --strict — both files PASSED — and the wheel carries exactly what you said:

Metadata-Version: 2.4
License-Expression: BSD-2-Clause
License-File: LICENSE          (shipped at smda-4.7.0.dist-info/licenses/LICENSE)
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3.11 / 3.12 / 3.13 / 3.14
Project-URL: Homepage, Repository, Issues, Changelog

The four documentation points

All four fixed in 6715097, each in the way I would have written it:

  • the smda entry point clause is gone from the build description;
  • the CI gate now says it reads ci.yml only, and names the benchmark as the one to confirm by eye — which is better than what I suggested, since it says why the narrow gate is deliberate rather than just what it covers;
  • the rehearsal section says the first one needs a tag cut after this workflow exists;
  • the heading form is aligned to ## [vX.Y.Z] throughout, and the guard's error message now names both forms instead of steering toward the one this file does not use. That is the right resolution for a script four other repositories share.

Re-ran the guard against the real tree at this head: v4.7.0 still passes, version=4.7.0 prerelease=false, 12 tests in 0.04s. All 24 checks pass — 24 rather than 22, which is the restored 3.11 legs showing up.

The policy

The Supported Python versions section is the part that will still be doing work in a year. Stating the resolver mechanism — that a floor raised alone becomes a silent downgrade rather than an error — is what makes the rule hold up when someone later asks why SMDA is waiting on MCRIT. Same for recording that UP rules make the bump non-reversible; that is the detail a future reader would otherwise have to rediscover by reverting and finding it did not work.

Merging. Thank you for the two follow-ups inside a day, and for checking 3.11 compatibility two ways rather than installing an interpreter unasked.

🤖 Generated with Claude Code

@danielplohmann
danielplohmann merged commit 669153c into danielplohmann:master Sep 14, 2026
27 checks passed
@r0ny123
r0ny123 deleted the ci/release-workflow branch September 14, 2026 12:13
@danielplohmann danielplohmann added this to the v4.8.0 milestone Sep 14, 2026
@danielplohmann danielplohmann mentioned this pull request Sep 14, 2026
danielplohmann added a commit to r0ny123/purepdb that referenced this pull request Sep 15, 2026
Two places where this repository had drifted from the shape smda merged in
danielplohmann/smda#343.

The milestone gate: verify refuses a tag whose milestone still has open items,
and release closes that milestone once the release exists. Both steps are
byte-identical to smda's, so the ecosystem keeps one thing to fix rather than
two that resemble each other. A tag with no milestone emits a notice and
releases, which is what makes this adoptable here -- purepdb's one milestone is
named `0.3.0` without the `v`, so nothing matches a tag until a release is
tracked that way deliberately.

The Python floor: smda's RELEASING.md names purepdb as one of the conditions
for moving off 3.11, so the reasoning has to exist on this side too. Framed the
way it actually applies here rather than copied: purepdb is at the bottom of
the stack -- smda depends on `purepdb>=0.3.0` unbounded, MCRIT reaches it
through smda -- so this floor constrains what is above it instead of following
it, and raising it alone would silently resolve smda back to an older purepdb
on 3.11 with nothing reporting the downgrade.

Verified: the gate's jq run verbatim against this repository's API in both
branches it can reach -- no milestone for `v0.6.0` (notice), `0.3.0` at 100%
(pass); the open-items branch has no milestone here to exercise it, and is
smda's own tested code. zizmor --persona=regular clean, 601 passed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
danielplohmann pushed a commit to danielplohmann/purepdb that referenced this pull request Sep 15, 2026
…e memory before

Releasing purepdb was `make publish` with an API token, and the tag workflow
only attached artefacts to a release with generated notes. Every check around a
release lived in whoever was doing it: that the tag matches `pyproject.toml`
*and* `purepdb/__init__.py`, that the version has a changelog section, that the
commit is on `main` and that CI went green on it. None of that is visible
afterwards, and a version yanked from PyPI stays unusable under that number
forever.

`.github/workflows/publish-release.yml` replaces `release.yml`. Pushing a
`vX.Y.Z` tag now verifies, builds, publishes and releases:

- **verify** refuses the tag unless it matches both version strings, `CHANGELOG.md`
  has a `## [X.Y.Z] - <date>` section (which becomes the release notes), the
  commit is an ancestor of `main`, CI concluded `success` on it, and a milestone
  named for the tag, if one exists, has no open items;
- **build** runs `python -m build` in isolation and `twine check --strict`, then
  installs the wheel into a clean venv and imports it under `python -P`, so the
  checkout cannot stand in for the artefact;
- **publish** uploads through trusted publishing with `id-token: write` as the
  only credential and attestations on — no token is stored anywhere;
- **release** creates the GitHub release with the changelog section as its body
  and `--generate-notes` appended, attaches the sdist and wheel, and closes the
  milestone. Pre-release tags are marked and never become latest.

A manual run rehearses the whole path against TestPyPI and stops before the
release.

The hand-written `CHANGELOG.md` is the single stream of change information: a new
`Changelog` check requires an entry from any PR touching `purepdb/` or
`pyproject.toml`, or the `no-changelog` label. `.github/release.yml` groups the
dependency bumps so they do not sit between the real changes.

`release_guard.py` carries the parsing, with 13 tests, because the changelog
shape it reads is a convention. It is the same script across the ecosystem,
varying only in its `VERSION_SOURCES` table, so there is one thing to fix rather
than six that resemble each other.

`RELEASING.md` documents cutting, rehearsing, pre-releases, recovery, the Python
floor policy and the one-time maintainer configuration. The Python floor stays at
3.11: purepdb sits at the bottom of the stack — smda depends on it unbounded and
MCRIT reaches it through smda — so raising it alone would silently resolve smda
back to an older purepdb with nothing reporting the downgrade.

Still to be configured by a maintainer before a tag can publish: the PyPI trusted
publisher, a *pending* publisher on TestPyPI, the `pypi` and `testpypi`
environments, and the `no-changelog` label.

One of six pull requests giving the MCRIT ecosystem one release process, after
danielplohmann/smda#343.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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