Skip to content

Generate GitHub releases from the changelog section, starting with smda #342

Closed

Description

@danielplohmann

Decision record from the discussion on 2026-09-11, so the reasoning survives the session that produced it. Nothing is implemented yet; smda goes first deliberately.

The question

The repository publishes to PyPI and keeps history in CHANGELOG.md, so distribution and history are already covered. What is left for a GitHub release to do?

Four things a release does that a tag cannot

  1. A semantic "latest". Tag ordering is lexicographic, so v4.10.0 sorts below v4.5.0 — one minor version from now, anything reading the tag list for "newest smda" gets the wrong answer. /releases/latest is defined as the most recent non-prerelease release and cannot. This is the same class of error as the changelog ordering bug docs(docs): adopt keep-a-changelog with an Unreleased section #337 fixed, which survived 186 entries because nobody can see it by eye.
  2. "Watch → Releases only". That subscription does not exist for this repository today, because there is nothing to subscribe to.
  3. Landing-page presence. 262 stars and 40 forks say the GitHub page is a real front door, plausibly ahead of PyPI for this kind of tool. A visitor currently sees no version information without digging into /tags.
  4. Zenodo DOI minting, which hooks on releases rather than tags. Optional, noted rather than argued for.

Decisions

Release bodies are extracted from CHANGELOG.md, not generated. #337 made the changelog machine-parseable — ## [vX.Y.Z] - YYYY-MM-DD headings over a fixed subsection set — so the body can be lifted from the section for that tag. One source of truth and no second copy to drift.

The alternative, gh release create --generate-notes, is what purepdb does today. It emits a bulleted list of merged PRs and a compare link. For an entry like #327's — 72 AArch64 ELF cells 95.994 → 97.063 PPV (−683 false positives)... not reproducible from the bundled fixtures — that collapses to "refuse a candidate the image declares interior by @r0ny123 in #327". The measurement, the corpus, the provenance caveat and the cost all vanish, and those are precisely what #323 spent ten points agreeing the entries must carry.

smda goes first, and the rest scale out from here. It is the most active repository of the family and therefore produces the most evidence about whether the workflow actually holds up. Porting outward before it has run for a release or two would be committing three repositories to an untested shape.

The manual alternative has already been tried in this family and did not survive. mcrit's newest release object is v1.3.0 from January 2024, hand-titled "Milestone Release"; its current version is 1.9.0. Six minor versions with no release, and /releases/latest now actively misinforms. mcritweb has none; docker-mcrit has one from 2023. A release step that depends on remembering is the thing being designed against.

Two pieces of purepdb's release.yml are worth keeping regardless of how the body is produced: the check that fails the build unless the tag equals the packaged version — the same class of mistake the "tag after green" rule guards, caught mechanically — and attaching the built artefacts after twine check, so the release carries the exact wheel and sdist that were verified.

Scope

Out of scope for now, both deliberately: automating the PyPI publish (currently make publish via twine; moving it into CI needs a stored token or a Trusted Publisher, which is a separate decision), and backfilling smda's 13 historical tags.

mcritweb and docker-mcrit are not part of this tier at all. Neither has a pyproject.toml or a changelog, so a release there would be the primary distribution artefact rather than a marker beside a PyPI upload, and would need upgrade and migration notes that do not exist yet. A changelog is the prerequisite.

Shape, when it is built

A workflow on push: tags: v* that extracts the section for the tag out of CHANGELOG.md, creates the release with it as the body, verifies tag == packaged version, and attaches the checked artefacts. Written as a plain workflow here first; promoted to a reusable workflow_call once purepdb and mcrit adopt it, so there is one thing to pin and fix rather than three copies drifting.

Activity

  1. danielplohmann commented on Sep 14, 2026

    @danielplohmann
    OwnerAuthor

    #343 landed as 669153c and implements this for smda. Recording what is done against the shape above, and what still has to happen before this issue can close.

    Built, and beyond the shape sketched here: the workflow extracts the section for the tag out of CHANGELOG.md, creates the release with it as the body, verifies tag == packaged version, and attaches the artefacts twine check --strict passed — the four things this issue asked for. It also does the two things scoped out: it publishes to PyPI, through trusted publishing rather than a stored token, so that decision is made and there is no secret to rotate. And it adds three gates this issue did not ask for — the commit has to be an ancestor of master, ci.yml has to have concluded success on it, and the milestone named for the tag has to be empty.

    Still open, which is why this stays open: it has not run. Trusted publishing has to be configured on pypi.org and test.pypi.org before a tag can publish anything, and the first rehearsal needs a throwaway pre-release tag cut after the merge, since a manual run uses the workflow file as it exists at the chosen tag and no existing tag has one. Until a release has actually gone through it, the evidence this issue wanted from smda going first does not exist yet.

    The four things a release does that a tag cannot are still unaddressed for the 13 historical tags, and backfilling stays out of scope as written. Worth noting that /releases/latest will start answering correctly from the first release cut this way, which is the item that decays fastest: v4.10.0 sorting below v4.5.0 is one minor version away.

    The ecosystem port is further along than "smda first, then scale out" anticipated — r0ny123 opened the same process against purepdb, mcrit, mcritweb, mcrit-plugin and docker-mcrit alongside #343. That does not change smda being the one that produces the evidence, but it does mean the promotion to a reusable workflow_call is a live question sooner than expected rather than after a release or two.

  2. danielplohmann commented on Sep 14, 2026

    @danielplohmann
    OwnerAuthor

    v4.8.0 was released through it today — the first release this repository has made without anyone holding an API token, and the first evidence this issue asked smda to produce.

    What the release object looks like in practice, which is the part that was argued rather than demonstrated: the changelog section leads the body, and GitHub's generated PR list and compare link sit underneath it. The entry for #343 reaches a reader intact — "the checks that previously lived in a person's memory" — where --generate-notes alone would have rendered the whole release as five PR titles. The measurement, the corpus and the provenance caveat survive, which was the entire argument for extracting rather than generating.

    Two gates ran for real that the v4.8.0rc1 rehearsal could not exercise:

    • the milestone gate, which reported a notice on the candidate because nothing was named v4.8.0rc1, passed at 0 open and then closed the milestone itself;
    • the publish, where the rehearsal only proved the reviewer gate blocks one. The pypi deployment was rejected on the candidate and approved here, so both directions of that gate are now known to work.

    /releases/latest answers correctly for the first time, which is item 1 of the four above and the one that decays fastest: v4.10.0 sorting below v4.5.0 is two minor versions away.

    Staying open until purepdb, MCRIT, MCRITweb, mcrit-plugin and docker-mcrit have adopted the full workflow rather than closing on smda alone. One release is evidence the shape holds; it is not yet evidence it ports. The promotion to a reusable workflow_call is the question to settle while they adopt, since the copies are what this issue set out to avoid.

    Backfilling the 13 historical tags stays out of scope, unchanged.

  3. danielplohmann commented on Sep 17, 2026

    @danielplohmann
    OwnerAuthor

    Closing this as a decision record that has been overtaken. The reasoning above stands as what was decided on 2026-09-11 and is worth leaving readable; the Scope section is no longer an accurate description of the work, which is the reason to stop pointing new ports at it.

    What shipped

    publish-release.yml, landed in #343 and first exercised for real on 2026-09-14. Pushing a vX.Y.Z tag builds, publishes to PyPI through trusted publishing, writes the GitHub release from that version's CHANGELOG.md section and closes the milestone, behind five gates. v4.8.0 went out at 15:46:51Z with no API token anywhere in the path.

    Two defects were found by rehearsing it rather than reading it, and both shipped fixed in v4.8.0: report import did not order PEP 440 pre-releases (#345), and three packaging guards rejected a candidate version outright (#346) — which meant the pre-release path documented in RELEASING.md across six repositories could not be walked in any of them.

    Where this issue is now wrong

    1. "Automating the PyPI publish" is listed as out of scope. It shipped. Trusted publishing replaced make publish, which is a larger change than this issue contemplated and removed the stored-token question rather than deferring it.
    2. "mcritweb and docker-mcrit are not part of this tier at all." Both have open ports — Release on a tag, with pyproject.toml as the one place the version lives familiary/mcritweb#176 and Gate deployment changes on a changelog entry, and pin what CI runs familiary/docker-mcrit#12. The changelog prerequisite named here was met by giving them one.
    3. The adoption list is stale. smda and purepdb have both released through it; mcrit-plugin merged its port in its add verbose mode #15 under an ida-v* scheme; mcrit#193, Release on a tag, with pyproject.toml as the one place the version lives familiary/mcritweb#176, Gate deployment changes on a changelog entry, and pin what CI runs familiary/docker-mcrit#12 and Release on a tag through trusted publishing, with the checks that were memory before familiary/picblocks#5 are open.

    What is still open

    Only the workflow_call promotion, which now has its own issue: #355. It is one paragraph rather than sixty lines, so the next port reads the live question instead of a superseded scope section.

    Closing. See #343 for what was built and #355 for what is left.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions