From 92926da8d88bc43cd63aa569b3e95e8d034086cc Mon Sep 17 00:00:00 2001 From: r0ny123 <49360849+r0ny123@users.noreply.github.com> Date: Fri, 11 Sep 2026 23:29:59 +0530 Subject: [PATCH 1/4] ci(ci): release on a tag, with the checks that were memory before 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. --- .github/release.yml | 17 ++ .github/workflows/publish-release.yml | 255 +++++++++++++++++++++ .github/workflows/scripts/release_guard.py | 79 +++++++ AGENTS.md | 2 + CHANGELOG.md | 8 + tests/testReleaseGuard.py | 145 ++++++++++++ 6 files changed, 506 insertions(+) create mode 100644 .github/release.yml create mode 100644 .github/workflows/publish-release.yml create mode 100644 .github/workflows/scripts/release_guard.py create mode 100644 tests/testReleaseGuard.py diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 00000000..b806bd56 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,17 @@ +# Not a workflow: GitHub reads the generated-release-notes configuration from this path and +# nowhere else. The workflow that cuts a release is `.github/workflows/publish-release.yml`. +changelog: + categories: + - title: Changes + labels: + - "*" + exclude: + labels: + - dependencies + - github_actions + - pre_commit + - title: Dependency and tooling updates + labels: + - dependencies + - github_actions + - pre_commit diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml new file mode 100644 index 00000000..47a80c30 --- /dev/null +++ b/.github/workflows/publish-release.yml @@ -0,0 +1,255 @@ +name: Publish release + +# A manual run rehearses against TestPyPI and stops before the GitHub release. +on: + push: + tags: + - "v*" + workflow_dispatch: + +permissions: + contents: read + +# A cancelled publish can leave PyPI holding some files of a version and not others, and the +# version number cannot be reused afterwards. +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +defaults: + run: + shell: bash + +jobs: + verify: + name: Verify the tag + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + actions: read + issues: read + outputs: + version: ${{ steps.guard.outputs.version }} + steps: + - name: Refuse anything that is not a tag + env: + REF_TYPE: ${{ github.ref_type }} + REF_NAME: ${{ github.ref_name }} + run: | + if [ "${REF_TYPE}" != "tag" ]; then + echo "::error::Run this from a tag, not ${REF_TYPE} ${REF_NAME}." + exit 1 + fi + + - name: Checkout the tag + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.11" + + - name: Check the tag against the packaged version and the changelog + id: guard + env: + TAG: ${{ github.ref_name }} + run: | + python .github/workflows/scripts/release_guard.py --tag "${TAG}" --notes release-notes.md + echo "version=${TAG#v}" >> "${GITHUB_OUTPUT}" + + - name: Check the tag is on master + env: + TAG: ${{ github.ref_name }} + run: | + git fetch --quiet origin master + if ! git merge-base --is-ancestor "${TAG}" origin/master; then + echo "::error::${TAG} is not an ancestor of master; releases are cut from master." + exit 1 + fi + + - name: Check CI passed on this commit + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + SHA: ${{ github.sha }} + run: | + conclusion=$(gh api \ + "repos/${REPO}/actions/workflows/ci.yml/runs?head_sha=${SHA}&status=completed" \ + --jq '.workflow_runs[0].conclusion // ""') + if [ -z "${conclusion}" ]; then + echo "::error::No completed CI run for ${SHA}. Wait for master to go green, then re-run." + exit 1 + fi + if [ "${conclusion}" != "success" ]; then + echo "::error::CI concluded '${conclusion}' for ${SHA}. Fix master before releasing." + exit 1 + fi + echo "CI passed on ${SHA}" + + - name: Check the milestone for this tag is finished + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + TAG: ${{ github.ref_name }} + run: | + open_items=$(gh api "repos/${REPO}/milestones?state=all&per_page=100" \ + --jq "[.[] | select(.title == \"${TAG}\")] | .[0].open_issues // \"none\"") + if [ "${open_items}" = "none" ]; then + echo "::notice::No milestone named ${TAG}; releasing without one." + elif [ "${open_items}" != "0" ]; then + echo "::error::Milestone ${TAG} still has ${open_items} open item(s)." + exit 1 + else + echo "Milestone ${TAG} reads 100%" + fi + + - name: Keep the release notes for the later jobs + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: release-notes + path: release-notes.md + if-no-files-found: error + + build: + name: Build and check the distribution + needs: verify + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout the tag + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.11" + + - name: Build the sdist and the wheel + run: | + python -m pip install --upgrade pip build twine + python -m build + python -m twine check --strict dist/* + + - name: Disassemble with the built wheel, runtime dependencies only + env: + VERSION: ${{ needs.verify.outputs.version }} + run: | + python -m venv /tmp/smoke + /tmp/smoke/bin/python -m pip install --upgrade pip + /tmp/smoke/bin/python -m pip install "dist/smda-${VERSION}-py3-none-any.whl" + /tmp/smoke/bin/python - <<'PY' + import os + import pathlib + + import smda + from smda.Disassembler import Disassembler + from smda.SmdaConfig import SmdaConfig + + installed = pathlib.Path(smda.__file__).parent + assert "site-packages" in str(installed), f"imported a source tree: {installed}" + assert smda.__version__ == os.environ["VERSION"], smda.__version__ + assert (installed / "py.typed").exists(), "py.typed did not ship" + + raw = pathlib.Path("tests/cutwail_xored").read_bytes() + report = Disassembler(SmdaConfig()).disassembleUnmappedBuffer( + bytes(byte ^ (index % 256) for index, byte in enumerate(raw)) + ) + assert report.status == "ok", report.status + assert report.num_functions > 0, "the wheel recovered nothing" + print(f"smda {smda.__version__}: {report.num_functions} functions, status {report.status}") + PY + + - name: Keep the distribution for the later jobs + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: distribution + path: dist/ + if-no-files-found: error + + publish: + name: Publish to ${{ github.event_name == 'workflow_dispatch' && 'TestPyPI' || 'PyPI' }} + needs: [verify, build] + runs-on: ubuntu-latest + timeout-minutes: 15 + environment: + name: ${{ github.event_name == 'workflow_dispatch' && 'testpypi' || 'pypi' }} + url: ${{ github.event_name == 'workflow_dispatch' && 'https://test.pypi.org/p/smda' || 'https://pypi.org/p/smda' }} + permissions: + # mandatory for trusted publishing, and it must be the only credential in the job + id-token: write + steps: + - name: Fetch the distribution + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: distribution + path: dist + + - name: Publish + uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2 + with: + # empty resolves to PyPI: the canonical input carries no default and the action falls + # through to the deprecated alias, which defaults to the real index + repository-url: ${{ github.event_name == 'workflow_dispatch' && 'https://test.pypi.org/legacy/' || '' }} + # a PyPI collision means the version is already public, so only a rehearsal skips it + skip-existing: ${{ github.event_name == 'workflow_dispatch' }} + attestations: true + print-hash: true + + release: + name: Create the GitHub release + needs: [verify, build, publish] + if: github.event_name != 'workflow_dispatch' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write + issues: write + steps: + - name: Fetch the distribution + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: distribution + path: dist + + - name: Fetch the release notes + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: release-notes + + # --generate-notes appends its list under --notes-file rather than replacing it, so the + # changelog section leads and `.github/release.yml` groups what follows + - name: Create the release + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + TAG: ${{ github.ref_name }} + run: | + shopt -s failglob + gh release create "${TAG}" dist/* \ + --repo "${REPO}" \ + --title "${TAG}" \ + --notes-file release-notes.md \ + --generate-notes \ + --verify-tag \ + --latest + + - name: Close the milestone for this tag + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + TAG: ${{ github.ref_name }} + run: | + number=$(gh api "repos/${REPO}/milestones?state=open&per_page=100" \ + --jq "[.[] | select(.title == \"${TAG}\")] | .[0].number // \"\"") + if [ -z "${number}" ]; then + echo "No open milestone named ${TAG}; nothing to close." + else + gh api -X PATCH "repos/${REPO}/milestones/${number}" -f state=closed >/dev/null + echo "Closed milestone ${TAG}" + fi diff --git a/.github/workflows/scripts/release_guard.py b/.github/workflows/scripts/release_guard.py new file mode 100644 index 00000000..fec66b68 --- /dev/null +++ b/.github/workflows/scripts/release_guard.py @@ -0,0 +1,79 @@ +"""Checks that decide whether a tag may be released, and the notes that go with it. + +A script rather than inline workflow steps so the parsing has tests: the changelog format it +reads is a convention, and a release is the one action here that cannot be undone. +""" + +import argparse +import re +import sys +from pathlib import Path + +#: `## [v4.7.0] - 2026-09-20`, the heading a release section opens with. +SECTION = re.compile(r"^## \[v(?P[\d.]+)\] - (?P\d{4}-\d{2}-\d{2})\s*$") +#: any second-level heading, which is where a section ends +NEXT_HEADING = re.compile(r"^## ") + + +def declaredVersions(root: Path) -> dict: + """The version as each of the two places that carry it states it.""" + found = {} + for label, path, pattern in ( + ("smda.__version__", root / "src" / "smda" / "__init__.py", r'^__version__ = "([\d.]+)"'), + ("SmdaConfig.VERSION", root / "src" / "smda" / "SmdaConfig.py", r'^\s+VERSION = "([\d.]+)"'), + ): + match = re.search(pattern, path.read_text(encoding="utf-8"), re.MULTILINE) + if match is None: + raise SystemExit(f"could not read a version from {path}") + found[label] = match.group(1) + return found + + +def changelogSection(changelog: str, version: str) -> str: + """The release notes for `version`, or a failure naming what is missing.""" + lines = changelog.splitlines() + for index, line in enumerate(lines): + match = SECTION.match(line) + if match is None or match.group("version") != version: + continue + body = [] + for following in lines[index + 1 :]: + if NEXT_HEADING.match(following): + break + body.append(following) + text = "\n".join(body).strip() + if not text: + raise SystemExit(f"CHANGELOG.md has a heading for v{version} but nothing under it") + return text + raise SystemExit( + f"CHANGELOG.md has no `## [v{version}] - ` section. " + "Rename `## [Unreleased]` to the release being cut before tagging." + ) + + +def main(argv: list) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--tag", required=True, help="the tag being released, e.g. v4.7.0") + parser.add_argument("--root", default=".", help="repository root") + parser.add_argument("--notes", help="write the release notes to this file") + args = parser.parse_args(argv) + + if not args.tag.startswith("v"): + raise SystemExit(f"tag {args.tag!r} does not start with 'v'") + version = args.tag[1:] + + versions = declaredVersions(Path(args.root)) + disagreeing = {label: value for label, value in versions.items() if value != version} + if disagreeing: + stated = ", ".join(f"{label} = {value}" for label, value in versions.items()) + raise SystemExit(f"tag {args.tag} does not match the packaged version ({stated})") + + notes = changelogSection((Path(args.root) / "CHANGELOG.md").read_text(encoding="utf-8"), version) + if args.notes: + Path(args.notes).write_text(notes + "\n", encoding="utf-8") + print(f"{args.tag} matches {versions['smda.__version__']} and has a changelog section") + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/AGENTS.md b/AGENTS.md index 4f5b8265..b5314012 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -128,6 +128,8 @@ the changelog records what landed and what it cost, the milestone what has not l **Tag after `master` is green, not at merge.** A tag created on the merge commit before CI has confirmed the merged tree can need moving, and moving one a PyPI publish has already consumed is a different problem from moving one nobody has fetched. +**Pushing the tag is the release.** `.github/workflows/publish-release.yml` builds, publishes to PyPI through trusted publishing, creates the GitHub release from this version's `CHANGELOG.md` section, and closes the milestone. Nothing above is left to remember at the console: it refuses to publish unless the tag matches both version strings, this version has a changelog section, the commit is on `master`, CI passed on that commit, and the milestone for the tag has no open items. Run the workflow manually from a tag first to rehearse the whole path against TestPyPI without touching PyPI. + Every other PR writes its own bullet under `## [Unreleased]` as it merges, rather than the release being reconstructed from merge commits afterwards — see *How an entry is written* in `CHANGELOG.md` for the subsections, the scope prefix and the four content rules. `.github/workflows/changelog.yml` requires a PR touching `src/smda/` to touch `CHANGELOG.md` or carry the `no-changelog` label. ## Git Workflow diff --git a/CHANGELOG.md b/CHANGELOG.md index 5bcbefc4..79751f06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -72,6 +72,14 @@ past roughly six lines it belongs in the PR the entry links. ### Added +- **(ci)** Pushing a `vX.Y.Z` tag now releases: the workflow builds, publishes to PyPI through + trusted publishing, creates the GitHub release from that version's changelog section, and closes + the milestone named for the tag. It refuses to publish unless the tag matches both version + strings, the version has a changelog section, the commit is on `master`, CI passed on that + commit, and the milestone has no open items — the checks that previously lived in a person's + memory between `make package` and `make publish`. No API token is stored anywhere, and each file + carries signed provenance. A manual run rehearses the whole path against TestPyPI. (#343) + ### Changed - **(tests)** `make test` now runs the fast tier and `make test-all` runs the whole suite. The `slow` diff --git a/tests/testReleaseGuard.py b/tests/testReleaseGuard.py new file mode 100644 index 00000000..8dcbc91b --- /dev/null +++ b/tests/testReleaseGuard.py @@ -0,0 +1,145 @@ +#!/usr/bin/python +"""Tests for the release gate (`.github/workflows/scripts/release_guard.py`). + +Its checks run once per release, minutes before the artifact becomes permanent, so here is the +only place they can be exercised before they matter. +""" + +import importlib.util +import tempfile +import unittest +from pathlib import Path + +_TESTS = Path(__file__).resolve().parent +_ROOT = _TESTS.parent +_SCRIPT = _ROOT / ".github" / "workflows" / "scripts" / "release_guard.py" + + +def _load_module(): + spec = importlib.util.spec_from_file_location("release_guard", _SCRIPT) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +guard = _load_module() + +CHANGELOG = """# Changelog + +## [Unreleased] + +### Fixed + +- **(intel)** something not yet released. (#1) + +## [v4.7.0] - 2026-09-20 + +### Changed + +- **(common)** the thing this release did. (#2) + +### Compatibility + +- recovery output moves. (#2) + +## [v4.6.0] - 2026-09-10 + +### Fixed + +- an older release. (#3) + +## Older releases + + * 2026-09-10: v4.6.0 - the one-line shape. +""" + + +class ChangelogSectionTest(unittest.TestCase): + def testTheSectionForAVersionIsReturned(self): + notes = guard.changelogSection(CHANGELOG, "4.7.0") + self.assertIn("the thing this release did", notes) + self.assertIn("### Compatibility", notes) + + def testTheSectionStopsAtTheNextRelease(self): + # without the stop it would swallow every older entry and the whole Older releases block + notes = guard.changelogSection(CHANGELOG, "4.7.0") + self.assertNotIn("an older release", notes) + self.assertNotIn("Older releases", notes) + + def testAnUnreleasedSectionIsNotAVersion(self): + # `## [Unreleased]` carries no date, so it cannot be mistaken for the release being cut + self.assertNotIn("not yet released", guard.changelogSection(CHANGELOG, "4.7.0")) + with self.assertRaises(SystemExit): + guard.changelogSection(CHANGELOG, "Unreleased") + + def testAMissingSectionFailsAndSaysWhatToDo(self): + with self.assertRaises(SystemExit) as raised: + guard.changelogSection(CHANGELOG, "4.8.0") + self.assertIn("Unreleased", str(raised.exception)) + + def testAHeadingWithNothingUnderItFails(self): + # renaming Unreleased without writing anything into it is the shape this catches + empty = "# Changelog\n\n## [v9.0.0] - 2026-01-01\n\n## Older releases\n" + with self.assertRaises(SystemExit): + guard.changelogSection(empty, "9.0.0") + + def testAnUndatedHeadingIsNotASection(self): + undated = "# Changelog\n\n## [v9.0.0]\n\n- something. (#1)\n" + with self.assertRaises(SystemExit): + guard.changelogSection(undated, "9.0.0") + + +class DeclaredVersionTest(unittest.TestCase): + def testBothVersionsAreReadFromTheRealTree(self): + versions = guard.declaredVersions(_ROOT) + self.assertEqual(set(versions), {"smda.__version__", "SmdaConfig.VERSION"}) + self.assertTrue(all(value for value in versions.values())) + + def testTheTwoAgreeInThisTree(self): + versions = guard.declaredVersions(_ROOT) + self.assertEqual(versions["smda.__version__"], versions["SmdaConfig.VERSION"]) + + +class MainTest(unittest.TestCase): + """The gate as the workflow calls it.""" + + def _tree(self, version, changelog): + root = Path(tempfile.mkdtemp()) + package = root / "src" / "smda" + package.mkdir(parents=True) + (package / "__init__.py").write_text(f'__version__ = "{version}"\n', encoding="utf-8") + (package / "SmdaConfig.py").write_text(f'class SmdaConfig:\n VERSION = "{version}"\n', encoding="utf-8") + (root / "CHANGELOG.md").write_text(changelog, encoding="utf-8") + return root + + def testAMatchingTagPassesAndWritesTheNotes(self): + root = self._tree("4.7.0", CHANGELOG) + notes = root / "notes.md" + self.assertEqual(guard.main(["--tag", "v4.7.0", "--root", str(root), "--notes", str(notes)]), 0) + self.assertIn("the thing this release did", notes.read_text(encoding="utf-8")) + + def testATagThatDisagreesWithThePackagedVersionFails(self): + # nothing else in the release notices that the tag names a different version + root = self._tree("4.6.0", CHANGELOG) + with self.assertRaises(SystemExit) as raised: + guard.main(["--tag", "v4.7.0", "--root", str(root)]) + self.assertIn("4.6.0", str(raised.exception)) + + def testATagWithoutTheVPrefixFails(self): + root = self._tree("4.7.0", CHANGELOG) + with self.assertRaises(SystemExit): + guard.main(["--tag", "4.7.0", "--root", str(root)]) + + def testOneVersionStringLaggingFails(self): + # the three-place bump with one place missed + root = self._tree("4.7.0", CHANGELOG) + (root / "src" / "smda" / "SmdaConfig.py").write_text( + 'class SmdaConfig:\n VERSION = "4.6.0"\n', encoding="utf-8" + ) + with self.assertRaises(SystemExit) as raised: + guard.main(["--tag", "v4.7.0", "--root", str(root)]) + self.assertIn("SmdaConfig.VERSION = 4.6.0", str(raised.exception)) + + +if __name__ == "__main__": + unittest.main() From 7dff5a7004dc34efb0783b88b4a640aab35450d7 Mon Sep 17 00:00:00 2001 From: r0ny123 <49360849+r0ny123@users.noreply.github.com> Date: Sun, 13 Sep 2026 00:52:18 +0530 Subject: [PATCH 2/4] ci(ci): share the release process with the rest of the MCRIT ecosystem 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. --- .github/release.yml | 9 +- .github/workflows/changelog.yml | 16 +-- .github/workflows/ci.yml | 22 ++--- .github/workflows/perf_benchmark.yml | 6 +- .github/workflows/profile.yml | 2 +- .github/workflows/publish-release.yml | 29 ++++-- .github/workflows/scripts/release_guard.py | 49 ++++++--- .github/workflows/security.yml | 4 +- AGENTS.md | 18 ++-- CHANGELOG.md | 20 +++- README.md | 2 +- RELEASING.md | 110 +++++++++++++++++++++ pyproject.toml | 16 +-- src/smda/SmdaConfig.py | 5 +- tests/testReleaseGuard.py | 52 +++++----- 15 files changed, 265 insertions(+), 95 deletions(-) create mode 100644 RELEASING.md diff --git a/.github/release.yml b/.github/release.yml index b806bd56..63fbd63a 100644 --- a/.github/release.yml +++ b/.github/release.yml @@ -1,6 +1,13 @@ # Not a workflow: GitHub reads the generated-release-notes configuration from this path and -# nowhere else. The workflow that cuts a release is `.github/workflows/publish-release.yml`. +# nowhere else. The release itself is cut by the workflow under `.github/workflows/`. +# +# The generated list is appended under the hand-written CHANGELOG.md section, so it exists to +# credit contributors and link every pull request, not to describe the release. Dependency and +# tooling bumps are grouped so they do not sit between the real changes. changelog: + exclude: + authors: + - github-actions[bot] categories: - title: Changes labels: diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index 33f37a7a..deac3439 100644 --- a/.github/workflows/changelog.yml +++ b/.github/workflows/changelog.yml @@ -14,7 +14,6 @@ on: - unlabeled branches: - master - - main permissions: contents: read @@ -28,7 +27,7 @@ jobs: # The job runs unconditionally and decides inside the step, rather than skipping on an # `if`: a skipped job reports as neither passing nor failing, and the reason a PR is # exempt belongs in the log where the next reader will look for it. - - name: Require a changelog entry beside an engine change + - name: Require a changelog entry beside a user-visible change env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} REPOSITORY: ${{ github.repository }} @@ -36,6 +35,7 @@ jobs: # contains() matches an array element exactly, so a label carrying a comma or a # name this one is a prefix of cannot be mistaken for it SKIP_LABELLED: ${{ contains(github.event.pull_request.labels.*.name, 'no-changelog') }} + IS_DEPENDABOT: ${{ github.event.pull_request.user.login == 'dependabot[bot]' }} run: | set -euo pipefail @@ -43,18 +43,22 @@ jobs: echo "Labelled no-changelog; entry not required." exit 0 fi + if [ "${IS_DEPENDABOT}" = "true" ]; then + echo "Dependency bump; the generated release notes list these under their own heading." + exit 0 + fi changed="$(gh api --paginate "repos/${REPOSITORY}/pulls/${PR_NUMBER}/files" --jq '.[].filename')" - if ! printf '%s\n' "${changed}" | grep -q '^src/smda/'; then - echo "No files under src/smda/ changed; entry not required." + if ! printf '%s\n' "${changed}" | grep -qE '^(src/smda/|pyproject.toml$)'; then + echo "No shipped files changed; entry not required." exit 0 fi if printf '%s\n' "${changed}" | grep -qx 'CHANGELOG.md'; then - echo "CHANGELOG.md touched beside the engine change." + echo "CHANGELOG.md touched beside the change." exit 0 fi - echo "::error file=CHANGELOG.md::This PR changes src/smda/ but does not touch CHANGELOG.md. Add an entry under ## Unreleased describing what moved and what it cost, or apply the no-changelog label if the change genuinely needs no entry." + echo "::error file=CHANGELOG.md::This PR changes shipped files but does not touch CHANGELOG.md. Add an entry under ## [Unreleased], or apply the no-changelog label if the change genuinely needs no entry." exit 1 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f2ece5a0..d44d7947 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -30,7 +30,7 @@ jobs: - name: Set up Python uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: - python-version: "3.11" + python-version: "3.12" cache: pip cache-dependency-path: pyproject.toml @@ -69,12 +69,12 @@ jobs: # Linux carries the full interpreter range; Windows and macOS run the floor # version only, to catch path/encoding portability without tripling the matrix. os: [ubuntu-latest] - python-version: ["3.11", "3.12", "3.13", "3.14"] + python-version: ["3.12", "3.13", "3.14"] include: - os: windows-latest - python-version: "3.11" + python-version: "3.12" - os: macos-latest - python-version: "3.11" + python-version: "3.12" steps: - name: Checkout code @@ -98,11 +98,11 @@ jobs: python -m pip install -e ".[dev]" - name: Run tests - if: matrix.os != 'ubuntu-latest' || matrix.python-version != '3.11' + if: matrix.os != 'ubuntu-latest' || matrix.python-version != '3.12' run: python -m pytest tests/test* - name: Run tests with coverage - if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' + if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' run: | set +e python -m pytest --cov=smda --cov-branch --cov-report=xml --cov-report=term-missing tests/ 2>&1 | tee coverage-summary.txt @@ -123,7 +123,7 @@ jobs: # Non-blocking for now: full coverage of changed source lines is a policy change, # and the metric gets observed over the next few PRs before it holds merges up. - name: Check diff coverage - if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' + if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' continue-on-error: true env: COMPARE_BRANCH: origin/${{ github.event.repository.default_branch }} @@ -142,7 +142,7 @@ jobs: exit "$status" - name: Upload coverage report - if: always() && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' + if: always() && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: coverage-report @@ -159,16 +159,12 @@ jobs: fail-fast: false matrix: os: [ubuntu-latest, windows-latest, macos-latest] - python-version: ["3.11", "3.12", "3.13", "3.14"] + python-version: ["3.12", "3.13", "3.14"] exclude: - - os: windows-latest - python-version: "3.11" - os: windows-latest python-version: "3.12" - os: windows-latest python-version: "3.13" - - os: macos-latest - python-version: "3.11" - os: macos-latest python-version: "3.12" - os: macos-latest diff --git a/.github/workflows/perf_benchmark.yml b/.github/workflows/perf_benchmark.yml index 952880e8..b65fc844 100644 --- a/.github/workflows/perf_benchmark.yml +++ b/.github/workflows/perf_benchmark.yml @@ -44,7 +44,7 @@ jobs: - name: Set up Python uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: - python-version: "3.11" + python-version: "3.12" cache: pip cache-dependency-path: pyproject.toml @@ -119,7 +119,7 @@ jobs: - name: Set up Python uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: - python-version: "3.11" + python-version: "3.12" cache: pip cache-dependency-path: pyproject.toml @@ -183,7 +183,7 @@ jobs: - name: Set up Python uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: - python-version: "3.11" + python-version: "3.12" - name: Download benchmark runs uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 diff --git a/.github/workflows/profile.yml b/.github/workflows/profile.yml index 7a0069b7..00ce6d9c 100644 --- a/.github/workflows/profile.yml +++ b/.github/workflows/profile.yml @@ -60,7 +60,7 @@ jobs: - name: Set up Python uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: - python-version: "3.11" + python-version: "3.12" cache: pip cache-dependency-path: pyproject.toml diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml index 47a80c30..a0e9745d 100644 --- a/.github/workflows/publish-release.yml +++ b/.github/workflows/publish-release.yml @@ -20,6 +20,9 @@ defaults: run: shell: bash +env: + PYTHON_VERSION: "3.12" + jobs: verify: name: Verify the tag @@ -31,6 +34,7 @@ jobs: issues: read outputs: version: ${{ steps.guard.outputs.version }} + prerelease: ${{ steps.guard.outputs.prerelease }} steps: - name: Refuse anything that is not a tag env: @@ -51,15 +55,15 @@ jobs: - name: Set up Python uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: - python-version: "3.11" + python-version: ${{ env.PYTHON_VERSION }} - name: Check the tag against the packaged version and the changelog id: guard env: TAG: ${{ github.ref_name }} run: | - python .github/workflows/scripts/release_guard.py --tag "${TAG}" --notes release-notes.md - echo "version=${TAG#v}" >> "${GITHUB_OUTPUT}" + python .github/workflows/scripts/release_guard.py \ + --tag "${TAG}" --notes release-notes.md --github-output "${GITHUB_OUTPUT}" - name: Check the tag is on master env: @@ -128,7 +132,7 @@ jobs: - name: Set up Python uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: - python-version: "3.11" + python-version: ${{ env.PYTHON_VERSION }} - name: Build the sdist and the wheel run: | @@ -136,14 +140,15 @@ jobs: python -m build python -m twine check --strict dist/* - - name: Disassemble with the built wheel, runtime dependencies only + # -P keeps the checkout off sys.path, so the import cannot fall back to the source tree + - name: Smoke-test the built wheel env: VERSION: ${{ needs.verify.outputs.version }} run: | python -m venv /tmp/smoke /tmp/smoke/bin/python -m pip install --upgrade pip - /tmp/smoke/bin/python -m pip install "dist/smda-${VERSION}-py3-none-any.whl" - /tmp/smoke/bin/python - <<'PY' + /tmp/smoke/bin/python -m pip install dist/smda-"${VERSION}"-py3-none-any.whl + /tmp/smoke/bin/python -P - <<'PY' import os import pathlib @@ -223,21 +228,27 @@ jobs: name: release-notes # --generate-notes appends its list under --notes-file rather than replacing it, so the - # changelog section leads and `.github/release.yml` groups what follows + # changelog section leads and `.github/release.yml` groups what follows. A pre-release + # is marked as such and never becomes "latest". - name: Create the release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} REPO: ${{ github.repository }} TAG: ${{ github.ref_name }} + PRERELEASE: ${{ needs.verify.outputs.prerelease }} run: | shopt -s failglob + flags=(--latest) + if [ "${PRERELEASE}" = "true" ]; then + flags=(--prerelease --latest=false) + fi gh release create "${TAG}" dist/* \ --repo "${REPO}" \ --title "${TAG}" \ --notes-file release-notes.md \ --generate-notes \ --verify-tag \ - --latest + "${flags[@]}" - name: Close the milestone for this tag env: diff --git a/.github/workflows/scripts/release_guard.py b/.github/workflows/scripts/release_guard.py index fec66b68..2257bd96 100644 --- a/.github/workflows/scripts/release_guard.py +++ b/.github/workflows/scripts/release_guard.py @@ -2,26 +2,41 @@ A script rather than inline workflow steps so the parsing has tests: the changelog format it reads is a convention, and a release is the one action here that cannot be undone. + +The same script, with a different VERSION_SOURCES table, guards every repository in the MCRIT +ecosystem. Keep the logic identical across them and vary only the table. """ import argparse import re import sys +import tomllib from pathlib import Path -#: `## [v4.7.0] - 2026-09-20`, the heading a release section opens with. -SECTION = re.compile(r"^## \[v(?P[\d.]+)\] - (?P\d{4}-\d{2}-\d{2})\s*$") +#: Where this repository states its version. Every entry has to agree with the tag. +#: ("label", "relative/path", regex-with-one-group) reads a literal from a text file; +#: ("label", "pyproject.toml", None) reads `[project].version`. +VERSION_SOURCES = [ + ("smda.__version__", "src/smda/__init__.py", r'^__version__ = "([0-9][0-9a-z.]*)"'), +] + +#: A release version as this ecosystem tags it: `1.2.3`, or a PEP 440 pre-release such as +#: `1.2.3rc1`, `1.2.3b2`, `1.2.3a1`. Anything else is refused rather than guessed at. +VERSION = re.compile(r"^(?P\d+\.\d+\.\d+)(?P
(a|b|rc)\d+)?$")
+#: `## [1.2.3] - 2026-09-20` (or `[v1.2.3]`), the heading a release section opens with.
+SECTION = re.compile(r"^## \[v?(?P[0-9][0-9a-z.]*)\] - (?P\d{4}-\d{2}-\d{2})\s*$")
 #: any second-level heading, which is where a section ends
 NEXT_HEADING = re.compile(r"^## ")
 
 
 def declaredVersions(root: Path) -> dict:
-    """The version as each of the two places that carry it states it."""
+    """The version as each place that carries it states it."""
     found = {}
-    for label, path, pattern in (
-        ("smda.__version__", root / "src" / "smda" / "__init__.py", r'^__version__ = "([\d.]+)"'),
-        ("SmdaConfig.VERSION", root / "src" / "smda" / "SmdaConfig.py", r'^\s+VERSION = "([\d.]+)"'),
-    ):
+    for label, relative, pattern in VERSION_SOURCES:
+        path = root / relative
+        if pattern is None:
+            found[label] = tomllib.loads(path.read_text(encoding="utf-8"))["project"]["version"]
+            continue
         match = re.search(pattern, path.read_text(encoding="utf-8"), re.MULTILINE)
         if match is None:
             raise SystemExit(f"could not read a version from {path}")
@@ -43,24 +58,29 @@ def changelogSection(changelog: str, version: str) -> str:
             body.append(following)
         text = "\n".join(body).strip()
         if not text:
-            raise SystemExit(f"CHANGELOG.md has a heading for v{version} but nothing under it")
+            raise SystemExit(f"CHANGELOG.md has a heading for {version} but nothing under it")
         return text
     raise SystemExit(
-        f"CHANGELOG.md has no `## [v{version}] - ` section. "
+        f"CHANGELOG.md has no `## [{version}] - ` section. "
         "Rename `## [Unreleased]` to the release being cut before tagging."
     )
 
 
 def main(argv: list) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--tag", required=True, help="the tag being released, e.g. v4.7.0")
+    parser.add_argument("--tag", required=True, help="the tag being released, e.g. v1.2.0")
     parser.add_argument("--root", default=".", help="repository root")
     parser.add_argument("--notes", help="write the release notes to this file")
+    parser.add_argument("--github-output", help="append version= and prerelease= to this file")
     args = parser.parse_args(argv)
 
     if not args.tag.startswith("v"):
         raise SystemExit(f"tag {args.tag!r} does not start with 'v'")
     version = args.tag[1:]
+    shape = VERSION.match(version)
+    if shape is None:
+        shape_wanted = "vMAJOR.MINOR.PATCH with an optional a/b/rc pre-release suffix"
+        raise SystemExit(f"tag {args.tag!r} is not {shape_wanted}")
 
     versions = declaredVersions(Path(args.root))
     disagreeing = {label: value for label, value in versions.items() if value != version}
@@ -68,10 +88,15 @@ def main(argv: list) -> int:
         stated = ", ".join(f"{label} = {value}" for label, value in versions.items())
         raise SystemExit(f"tag {args.tag} does not match the packaged version ({stated})")
 
-    notes = changelogSection((Path(args.root) / "CHANGELOG.md").read_text(encoding="utf-8"), version)
+    changelog = (Path(args.root) / "CHANGELOG.md").read_text(encoding="utf-8")
+    notes = changelogSection(changelog, version)
     if args.notes:
         Path(args.notes).write_text(notes + "\n", encoding="utf-8")
-    print(f"{args.tag} matches {versions['smda.__version__']} and has a changelog section")
+    if args.github_output:
+        prerelease = "true" if shape.group("pre") else "false"
+        with open(args.github_output, "a", encoding="utf-8") as output:
+            output.write(f"version={version}\nprerelease={prerelease}\n")
+    print(f"{args.tag} matches the declared version and has a changelog section")
     return 0
 
 
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
index a222de70..45858b69 100644
--- a/.github/workflows/security.yml
+++ b/.github/workflows/security.yml
@@ -34,7 +34,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           cache: pip
           cache-dependency-path: pyproject.toml
 
@@ -79,7 +79,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Install zizmor
         run: |
diff --git a/AGENTS.md b/AGENTS.md
index b5314012..5e2b8d91 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -90,7 +90,7 @@ Pre-commit hooks (ruff + standard hygiene checks) run on commit via `.pre-commit
 
 ## Code Conventions
 
-- **Formatter / linter:** Ruff. Line length **120**, target **Python 3.11+** (`py311`).
+- **Formatter / linter:** Ruff. Line length **120**, target **Python 3.12+** (`py312`).
 - **Style:** Ruff `select` set is `E4, E7, E9, F, W, I, UP, B, C4, PIE, SIM`. `E501` is ignored (formatter handles length). `UP006`/`UP007` are intentionally ignored to avoid sweeping typing modernization churn.
 - **No comments in code** unless explicitly requested. Keep code self-documenting via clear names and structure.
 - **Imports:** `src`-layout package. Import as `from smda....` (the installed/editable package), never relative path hacks. Ruff's `I` rule enforces import ordering.
@@ -111,13 +111,7 @@ ida_analyze.py   # IDA-side analysis/export helper
 
 ## Versioning & Releases
 
-When a change warrants a version bump, update **all three** in one commit:
-
-1. `src/smda/__init__.py` → `__version__`
-2. `src/smda/SmdaConfig.py` → `SmdaConfig.VERSION`
-3. `CHANGELOG.md` → rename `## [Unreleased]` to `## [vX.Y.Z] - YYYY-MM-DD`, drop the subsections the release did not use, open a fresh empty `## [Unreleased]` above it, and update the compare links at the foot of the file.
-
-Keep the two version strings in sync. Do not bump versions unless the change is a release-worthy change (and see Git Workflow re: explicit ask).
+The version is declared once, in `src/smda/__init__.py` (`__version__`); `pyproject.toml` reads it dynamically and `SmdaConfig.VERSION` imports it. A release bumps that line and `CHANGELOG.md` in one commit: rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`, drop the subsections the release did not use, open a fresh empty `## [Unreleased]` above it, and update the compare links at the foot of the file. Do not bump the version unless the change is a release-worthy change (and see Git Workflow re: explicit ask).
 
 **Scope lives in a milestone named for the tag.** A PR joins `vX.Y.Z` when it is accepted for that
 release rather than when it is opened, so the milestone stays a list of what is left rather than a
@@ -128,9 +122,9 @@ the changelog records what landed and what it cost, the milestone what has not l
 
 **Tag after `master` is green, not at merge.** A tag created on the merge commit before CI has confirmed the merged tree can need moving, and moving one a PyPI publish has already consumed is a different problem from moving one nobody has fetched.
 
-**Pushing the tag is the release.** `.github/workflows/publish-release.yml` builds, publishes to PyPI through trusted publishing, creates the GitHub release from this version's `CHANGELOG.md` section, and closes the milestone. Nothing above is left to remember at the console: it refuses to publish unless the tag matches both version strings, this version has a changelog section, the commit is on `master`, CI passed on that commit, and the milestone for the tag has no open items. Run the workflow manually from a tag first to rehearse the whole path against TestPyPI without touching PyPI.
+**Pushing the tag is the release.** `.github/workflows/publish-release.yml` builds, publishes to PyPI through trusted publishing, creates the GitHub release from this version's `CHANGELOG.md` section, and closes the milestone. It refuses to publish unless the tag matches `__version__`, this version has a changelog section, the commit is on `master`, CI passed on that commit, and the milestone for the tag has no open items. The full procedure — cutting, rehearsing against TestPyPI, pre-releases, recovery, what a maintainer configures once — is in [`RELEASING.md`](RELEASING.md), which is the same process every MCRIT ecosystem repository follows.
 
-Every other PR writes its own bullet under `## [Unreleased]` as it merges, rather than the release being reconstructed from merge commits afterwards — see *How an entry is written* in `CHANGELOG.md` for the subsections, the scope prefix and the four content rules. `.github/workflows/changelog.yml` requires a PR touching `src/smda/` to touch `CHANGELOG.md` or carry the `no-changelog` label.
+Every other PR writes its own bullet under `## [Unreleased]` as it merges, rather than the release being reconstructed from merge commits afterwards — see *How an entry is written* in `CHANGELOG.md` for the subsections, the scope prefix and the four content rules. `.github/workflows/changelog.yml` requires a PR touching `src/smda/` or `pyproject.toml` to touch `CHANGELOG.md` or carry the `no-changelog` label.
 
 ## Git Workflow
 
@@ -147,7 +141,7 @@ Every other PR writes its own bullet under `## [Unreleased]` as it merges, rathe
 - Mark a test `slow` (`pytestmark = pytest.mark.slow`, or per-test) when it disassembles a real fixture corpus. Marking one keeps the default loop fast; forgetting to mark one is what makes it slow again.
 - Architecture-specific behavior (intel / aarch64 / cil / dalvik) should be covered with representative fixtures where feasible.
 - The xored `tests/*_xored` corpora and the malpedia **benchmark matrix (`.github/workflows/perf_benchmark.yml`) are PR/CI-only** — they require a password-gated malpedia corpus and are not expected to run locally. For local recovery-quality validation, the maintainer works against separate groundtruth datasets rather than the full public matrix. Do not assume you can reproduce the benchmark suite locally.
-- Run tests with `python -m pytest tests/test*` (or `make test`) against a Python 3.11+ environment with the `dev` extra installed.
+- Run tests with `python -m pytest tests/test*` (or `make test`) against a Python 3.12+ environment with the `dev` extra installed.
 
 ## Gotchas
 
@@ -186,7 +180,7 @@ Constraints an agent must respect to avoid breaking SMDA or its downstream consu
 - The feature is **experimental**: it works on well-formed reports but has not been hardened against pathological or adversarial inputs. The golden test fixtures cover one sample per format only.
 - `code_sections` names are **not preserved** through `SmdaReport.toDict()`/`fromDict()` round-trips (they come from LIEF metadata). Tests that mutate a report via `fromDict` must capture VA ranges before the round-trip.
 - Synthesis is deterministic from report content only — it does not consult `STORE_BUFFER`.
-- Install the toolchain with `python -m pip install -e ".[dev]"`; SMDA requires Python 3.11+.
+- Install the toolchain with `python -m pip install -e ".[dev]"`; SMDA requires Python 3.12+.
 
 ### Reality check — common traps for agents
 - **The pipeline description is intel-centric.** The `E8`/`FF 15`/`55 8B EC` heuristics and the gap-search/NOP-list logic belong to the intel backend. Other backends follow their own candidate/traversal logic (e.g. `cil` does essentially no gap search thanks to rich metadata). Do not apply intel assumptions to other architectures.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 79751f06..85b5f461 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -74,14 +74,24 @@ past roughly six lines it belongs in the PR the entry links.
 
 - **(ci)** Pushing a `vX.Y.Z` tag now releases: the workflow builds, publishes to PyPI through
   trusted publishing, creates the GitHub release from that version's changelog section, and closes
-  the milestone named for the tag. It refuses to publish unless the tag matches both version
-  strings, the version has a changelog section, the commit is on `master`, CI passed on that
+  the milestone named for the tag. It refuses to publish unless the tag matches the packaged
+  version, the version has a changelog section, the commit is on `master`, CI passed on that
   commit, and the milestone has no open items — the checks that previously lived in a person's
   memory between `make package` and `make publish`. No API token is stored anywhere, and each file
-  carries signed provenance. A manual run rehearses the whole path against TestPyPI. (#343)
+  carries signed provenance. Pre-release tags (`v4.7.0rc1`) are marked as such. A manual run
+  rehearses the whole path against TestPyPI. The process is documented in `RELEASING.md` and is
+  the one every MCRIT ecosystem repository follows. (#343)
 
 ### Changed
 
+- **(core)** `SmdaConfig.VERSION` is read from `smda.__version__` instead of being a second literal
+  kept in sync by hand, so a release bumps one line. `report.smda_version` is unchanged. (#343)
+
+- **(build)** `pyproject.toml` declares the license as the SPDX expression `BSD-2-Clause` with
+  `license-files` (PEP 639) instead of the free-text form and the deprecated license classifier,
+  and gains `Repository`, `Issues` and `Changelog` URLs. Building now needs `setuptools>=77`; the
+  wheel's metadata is otherwise unchanged. (#343)
+
 - **(tests)** `make test` now runs the fast tier and `make test-all` runs the whole suite. The `slow`
   marker already existed, was already applied to the eleven fixture-corpus files, and was documented in
   `pyproject.toml` with its own deselect recipe — but no entry point used it, so every local run paid for
@@ -104,6 +114,10 @@ past roughly six lines it belongs in the PR the entry links.
 
 ### Removed
 
+- **(build)** Python 3.11 is no longer supported; `requires-python` is `>=3.12`, and CI runs 3.12
+  through 3.14. Nothing in the engine needed 3.12 — the MCRIT ecosystem now shares a 3.12 floor so
+  one interpreter serves every component. (#343)
+
 ### Fixed
 
 - **(intel)** Resume the gap scan inside the gap a failed candidate was found in, rather than
diff --git a/README.md b/README.md
index e65f06d7..4505b851 100644
--- a/README.md
+++ b/README.md
@@ -191,7 +191,7 @@ Headless export requires IDA 9.1+ and the optional `ida-domain>=0.5.0` dependenc
 
 For Dalvik, the current scope is raw single-DEX inputs (`dex\n`). APK and multi-dex containers are not first-class workflows. ODEX (`dey\n`) and CDEX (`cdex`) are not analysis-compatible (quickened ops / compact `code_item`): with `backend="dalvik"` they raise an explicit error; auto-detect will not select the Dalvik backend for those magics.
 
-The code requires Python 3.11+.
+The code requires Python 3.12+.
 `SmdaReport.metadata.language` is always a score map (`language name -> float`). Internal guesses and evidence
 counters are not serialized; loading an older report normalizes its legacy string/private-key form to this contract.
 To pick a single language from the map, take the highest score, except that `go` and `rust` win outright when their
diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 00000000..8a663f99
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,110 @@
+# Releasing SMDA
+
+This repository follows the release process shared across the MCRIT ecosystem
+([smda](https://github.com/danielplohmann/smda), [purepdb](https://github.com/danielplohmann/purepdb),
+[mcrit](https://github.com/danielplohmann/mcrit), [mcritweb](https://github.com/fkie-cad/mcritweb),
+[mcrit-plugin](https://github.com/danielplohmann/mcrit-plugin),
+[docker-mcrit](https://github.com/danielplohmann/docker-mcrit)). The shape is the same everywhere;
+this file states the values that are specific to this repository.
+
+## Versioning
+
+**The SMDA version is a release counter, not semantic versioning.** The top of `CHANGELOG.md` says what
+that means and which three constants carry the compatibility promise for report consumers instead.
+Scope for a release is tracked in a GitHub milestone named for the tag (`v4.7.0`); see
+`AGENTS.md`, *Versioning & Releases*.
+
+The version is declared in `src/smda/__init__.py` (`__version__`; `pyproject.toml` reads it dynamically and
+`SmdaConfig.VERSION` imports it). The release workflow refuses a tag that does not
+match every one of them, so a bump that misses one fails before anything is published.
+
+## Changelog
+
+`CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). It is the one
+authoritative record of what a release contains: the GitHub release notes are generated from it, and
+nothing is written twice.
+
+- Every pull request that changes something a user can observe adds its own bullet under
+  `## [Unreleased]`, in the subsection it belongs to (`Added`, `Changed`, `Deprecated`, `Removed`,
+  `Fixed`, `Security`), while the change is fresh. The `Changelog` check fails a PR that touches
+  shipped files without touching `CHANGELOG.md`; apply the `no-changelog` label when a change
+  genuinely needs no entry (a typo, a CI-only change), and say why in the PR.
+- An entry says what changed and what it costs the reader: what to do when upgrading, what may
+  behave differently, which issue or PR it closes.
+- Dependency bumps need no entry. GitHub lists them under their own heading in the release notes,
+  from the `dependencies` / `github_actions` labels (`.github/release.yml`).
+
+## Cutting a release
+
+1. Check that `master` is green and that everything meant for the release has merged.
+2. In one commit on a branch, then merged through a PR:
+   - set the new version in `src/smda/__init__.py` (`__version__`; `pyproject.toml` reads it dynamically and
+`SmdaConfig.VERSION` imports it);
+   - in `CHANGELOG.md`, rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`, drop the empty
+     subsections, open a fresh empty `## [Unreleased]` above it, and update the compare links at
+     the foot of the file.
+3. Wait for CI to pass on the merge commit. Then tag that commit and push the tag:
+
+   ```bash
+   git tag -a vX.Y.Z -m "SMDA X.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+Pushing the tag is the release. `.github/workflows/publish-release.yml` then:
+
+1. **Verify** — refuses to continue unless the tag matches `__version__`, `CHANGELOG.md` has a
+   `## [X.Y.Z] - ` section (which becomes the release notes), the tagged commit is on
+   `master`, CI passed on that commit, and the milestone named for the tag, if there is one, has
+   no open items.
+2. **Build** — builds the sdist and wheel in an isolated environment, checks their metadata with
+   `twine check --strict`, and installs the wheel into a clean virtual environment carrying only
+   the declared runtime dependencies to disassemble a bundled sample with it and run the `smda`
+   entry point.
+3. **Publish** — uploads to PyPI through [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+   with signed provenance attestations. No API token is stored anywhere.
+4. **Release** — creates the GitHub release for the tag with the changelog section as its body,
+   GitHub's generated contributor and PR list appended under it, and the sdist and wheel attached;
+   then closes the milestone.
+
+Each gate fails with a message naming what to fix. Nothing has to be remembered at the console.
+
+## Pre-releases
+
+A release candidate is tagged `vX.Y.Zrc1` (also `a1`, `b1`), with the same version string in
+`src/smda/__init__.py` (`__version__`; `pyproject.toml` reads it dynamically and
+`SmdaConfig.VERSION` imports it) and a `## [X.Y.Zrc1] - YYYY-MM-DD` changelog section. The workflow marks the
+GitHub release as a pre-release and does not make it "latest". PyPI
+does not install a pre-release unless it is asked for explicitly (`pip install --pre`).
+
+## Rehearsing
+
+Run *Publish release* manually from the Actions tab, choosing a tag as the ref. A manual run goes
+through the same gates and build, publishes to [TestPyPI](https://test.pypi.org/p/smda) instead of
+PyPI (an already-present version is skipped rather than failed), and stops before creating the
+GitHub release. Rehearse the first release after any change to the workflow.
+
+## When a release fails
+
+- **A gate failed before anything was published** (tag/version mismatch, missing changelog section,
+  tag not on `master`, CI not green): fix the cause on `master`, delete the
+  tag locally and on the remote (`git push --delete origin vX.Y.Z`), and tag again once the fix has
+  merged. Nothing needs cleaning up.
+- **Publishing to PyPI failed part-way**: a version number on PyPI is permanent even when yanked,
+  so do not try to reuse it. Fix the cause, bump the patch version, and release again. Yank the
+  incomplete version on PyPI if any of its files were accepted.
+- **The GitHub release step failed after publishing**: re-run only the failed job from the Actions
+  UI; the built artifacts are kept as workflow artifacts and the step is idempotent.
+
+## Maintainer configuration
+
+Done once, by a repository owner; the workflow cannot create these for itself.
+
+- **PyPI trusted publisher** for the `smda` project: owner `danielplohmann`, repository `smda`,
+  workflow `publish-release.yml`, environment `pypi`. Add the same publisher on TestPyPI with
+  environment `testpypi` to enable rehearsals.
+- **GitHub environments** `pypi` and `testpypi` (Settings → Environments). Restricting `pypi` to
+  the `v*` tag pattern and requiring a reviewer is recommended: it makes the publish step a
+  deliberate click even if a tag is pushed by mistake.
+- **Label** `no-changelog` (already present), used by the changelog check.
+- Optionally, **immutable releases** (Settings → General → Releases), so a published release's
+  assets and tag can no longer be changed.
diff --git a/pyproject.toml b/pyproject.toml
index 8cfa3fed..92b2a9d5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,22 +1,21 @@
 [build-system]
-requires = ["setuptools>=64.0.0,<84.1.0", "wheel>=0.47.0"]
+requires = ["setuptools>=77,<84.1.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "smda"
 description = "A recursive disassmbler optimized for CFG recovery from memory dumps. Based on capstone."
 readme = "README.md"
-requires-python = ">=3.11"
-license = {text = "BSD 2-Clause"}
+requires-python = ">=3.12"
+license = "BSD-2-Clause"
+license-files = ["LICENSE"]
 authors = [
     {name = "Daniel Plohmann", email = "daniel.plohmann@mailbox.org"}
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
-    "License :: OSI Approved :: BSD License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
@@ -39,6 +38,9 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://github.com/danielplohmann/smda"
+Repository = "https://github.com/danielplohmann/smda"
+Issues = "https://github.com/danielplohmann/smda/issues"
+Changelog = "https://github.com/danielplohmann/smda/blob/master/CHANGELOG.md"
 
 [project.optional-dependencies]
 dev = [
@@ -148,8 +150,8 @@ directory = "coverage-html"
 # Same as Black.
 line-length = 120
 
-# Assume Python 3.11+
-target-version = "py311"
+# Assume Python 3.12+
+target-version = "py312"
 
 [tool.ruff.lint]
 # Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.
diff --git a/src/smda/SmdaConfig.py b/src/smda/SmdaConfig.py
index 545d9f29..39e567e5 100644
--- a/src/smda/SmdaConfig.py
+++ b/src/smda/SmdaConfig.py
@@ -1,10 +1,11 @@
 import logging
 import os
 
+from smda import __version__
+
 
 class SmdaConfig:
-    # keep this in sync with smda.__version__
-    VERSION = "4.6.0"
+    VERSION = __version__
     # Bump this whenever any architecture's InstructionEscaper changes its
     # output (mnemonic groups or escaped operands). Downstream indexes such as
     # MCRIT treat reports whose smda_version is below this value as stale.
diff --git a/tests/testReleaseGuard.py b/tests/testReleaseGuard.py
index 8dcbc91b..4a9ee31b 100644
--- a/tests/testReleaseGuard.py
+++ b/tests/testReleaseGuard.py
@@ -42,6 +42,12 @@ def _load_module():
 
 - recovery output moves. (#2)
 
+## [4.7.0rc1] - 2026-09-15
+
+### Added
+
+- the candidate. (#2)
+
 ## [v4.6.0] - 2026-09-10
 
 ### Fixed
@@ -63,9 +69,14 @@ def testTheSectionForAVersionIsReturned(self):
     def testTheSectionStopsAtTheNextRelease(self):
         # without the stop it would swallow every older entry and the whole Older releases block
         notes = guard.changelogSection(CHANGELOG, "4.7.0")
+        self.assertNotIn("the candidate", notes)
         self.assertNotIn("an older release", notes)
         self.assertNotIn("Older releases", notes)
 
+    def testAHeadingWithOrWithoutTheVPrefixIsASection(self):
+        self.assertIn("the candidate", guard.changelogSection(CHANGELOG, "4.7.0rc1"))
+        self.assertIn("an older release", guard.changelogSection(CHANGELOG, "4.6.0"))
+
     def testAnUnreleasedSectionIsNotAVersion(self):
         # `## [Unreleased]` carries no date, so it cannot be mistaken for the release being cut
         self.assertNotIn("not yet released", guard.changelogSection(CHANGELOG, "4.7.0"))
@@ -90,14 +101,10 @@ def testAnUndatedHeadingIsNotASection(self):
 
 
 class DeclaredVersionTest(unittest.TestCase):
-    def testBothVersionsAreReadFromTheRealTree(self):
-        versions = guard.declaredVersions(_ROOT)
-        self.assertEqual(set(versions), {"smda.__version__", "SmdaConfig.VERSION"})
-        self.assertTrue(all(value for value in versions.values()))
-
-    def testTheTwoAgreeInThisTree(self):
+    def testTheVersionIsReadFromTheRealTree(self):
         versions = guard.declaredVersions(_ROOT)
-        self.assertEqual(versions["smda.__version__"], versions["SmdaConfig.VERSION"])
+        self.assertEqual(set(versions), {"smda.__version__"})
+        self.assertRegex(versions["smda.__version__"], r"^\d+\.\d+\.\d+")
 
 
 class MainTest(unittest.TestCase):
@@ -108,15 +115,23 @@ def _tree(self, version, changelog):
         package = root / "src" / "smda"
         package.mkdir(parents=True)
         (package / "__init__.py").write_text(f'__version__ = "{version}"\n', encoding="utf-8")
-        (package / "SmdaConfig.py").write_text(f'class SmdaConfig:\n    VERSION = "{version}"\n', encoding="utf-8")
         (root / "CHANGELOG.md").write_text(changelog, encoding="utf-8")
         return root
 
-    def testAMatchingTagPassesAndWritesTheNotes(self):
+    def testAMatchingTagPassesAndWritesTheNotesAndOutputs(self):
         root = self._tree("4.7.0", CHANGELOG)
         notes = root / "notes.md"
-        self.assertEqual(guard.main(["--tag", "v4.7.0", "--root", str(root), "--notes", str(notes)]), 0)
+        output = root / "output.txt"
+        argv = ["--tag", "v4.7.0", "--root", str(root), "--notes", str(notes), "--github-output", str(output)]
+        self.assertEqual(guard.main(argv), 0)
         self.assertIn("the thing this release did", notes.read_text(encoding="utf-8"))
+        self.assertEqual(output.read_text(encoding="utf-8"), "version=4.7.0\nprerelease=false\n")
+
+    def testAPreReleaseTagIsFlagged(self):
+        root = self._tree("4.7.0rc1", CHANGELOG)
+        output = root / "output.txt"
+        self.assertEqual(guard.main(["--tag", "v4.7.0rc1", "--root", str(root), "--github-output", str(output)]), 0)
+        self.assertIn("prerelease=true", output.read_text(encoding="utf-8"))
 
     def testATagThatDisagreesWithThePackagedVersionFails(self):
         # nothing else in the release notices that the tag names a different version
@@ -125,20 +140,11 @@ def testATagThatDisagreesWithThePackagedVersionFails(self):
             guard.main(["--tag", "v4.7.0", "--root", str(root)])
         self.assertIn("4.6.0", str(raised.exception))
 
-    def testATagWithoutTheVPrefixFails(self):
-        root = self._tree("4.7.0", CHANGELOG)
-        with self.assertRaises(SystemExit):
-            guard.main(["--tag", "4.7.0", "--root", str(root)])
-
-    def testOneVersionStringLaggingFails(self):
-        # the three-place bump with one place missed
+    def testAMalformedTagFails(self):
         root = self._tree("4.7.0", CHANGELOG)
-        (root / "src" / "smda" / "SmdaConfig.py").write_text(
-            'class SmdaConfig:\n    VERSION = "4.6.0"\n', encoding="utf-8"
-        )
-        with self.assertRaises(SystemExit) as raised:
-            guard.main(["--tag", "v4.7.0", "--root", str(root)])
-        self.assertIn("SmdaConfig.VERSION = 4.6.0", str(raised.exception))
+        for tag in ("4.7.0", "v4.7", "v4.7.0-rc1", "v4.7.0.dev1", "vlatest"):
+            with self.subTest(tag=tag), self.assertRaises(SystemExit):
+                guard.main(["--tag", tag, "--root", str(root)])
 
 
 if __name__ == "__main__":

From 67150975c58c799230c09f856f85aad33c4f31f3 Mon Sep 17 00:00:00 2001
From: r0ny123 <49360849+r0ny123@users.noreply.github.com>
Date: Sun, 13 Sep 2026 14:40:49 +0530
Subject: [PATCH 3/4] docs(docs): make the release docs describe what the
 workflow does

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.
---
 .github/workflows/scripts/release_guard.py |  2 +-
 AGENTS.md                                  |  2 +-
 CHANGELOG.md                               |  4 +++-
 RELEASING.md                               | 22 +++++++++++++++-------
 4 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/scripts/release_guard.py b/.github/workflows/scripts/release_guard.py
index 2257bd96..2b46620b 100644
--- a/.github/workflows/scripts/release_guard.py
+++ b/.github/workflows/scripts/release_guard.py
@@ -61,7 +61,7 @@ def changelogSection(changelog: str, version: str) -> str:
             raise SystemExit(f"CHANGELOG.md has a heading for {version} but nothing under it")
         return text
     raise SystemExit(
-        f"CHANGELOG.md has no `## [{version}] - ` section. "
+        f"CHANGELOG.md has no `## [{version}] - ` or `## [v{version}] - ` section. "
         "Rename `## [Unreleased]` to the release being cut before tagging."
     )
 
diff --git a/AGENTS.md b/AGENTS.md
index 5e2b8d91..949999aa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -111,7 +111,7 @@ ida_analyze.py   # IDA-side analysis/export helper
 
 ## Versioning & Releases
 
-The version is declared once, in `src/smda/__init__.py` (`__version__`); `pyproject.toml` reads it dynamically and `SmdaConfig.VERSION` imports it. A release bumps that line and `CHANGELOG.md` in one commit: rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`, drop the subsections the release did not use, open a fresh empty `## [Unreleased]` above it, and update the compare links at the foot of the file. Do not bump the version unless the change is a release-worthy change (and see Git Workflow re: explicit ask).
+The version is declared once, in `src/smda/__init__.py` (`__version__`); `pyproject.toml` reads it dynamically and `SmdaConfig.VERSION` imports it. A release bumps that line and `CHANGELOG.md` in one commit: rename `## [Unreleased]` to `## [vX.Y.Z] - YYYY-MM-DD`, drop the subsections the release did not use, open a fresh empty `## [Unreleased]` above it, and update the compare links at the foot of the file. Do not bump the version unless the change is a release-worthy change (and see Git Workflow re: explicit ask).
 
 **Scope lives in a milestone named for the tag.** A PR joins `vX.Y.Z` when it is accepted for that
 release rather than when it is opened, so the milestone stays a list of what is left rather than a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fb6e0e75..b9a729e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -98,7 +98,9 @@ past roughly six lines it belongs in the PR the entry links.
 
 - **(build)** Python 3.11 is no longer supported; `requires-python` is `>=3.12`, and CI runs 3.12
   through 3.14. Nothing in the engine needed 3.12 — the MCRIT ecosystem now shares a 3.12 floor so
-  one interpreter serves every component. (#343)
+  one interpreter serves every component. This is not free for IDA users: 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. (#343)
 
 ### Fixed
 
diff --git a/RELEASING.md b/RELEASING.md
index 8a663f99..6c787987 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -40,7 +40,7 @@ nothing is written twice.
 2. In one commit on a branch, then merged through a PR:
    - set the new version in `src/smda/__init__.py` (`__version__`; `pyproject.toml` reads it dynamically and
 `SmdaConfig.VERSION` imports it);
-   - in `CHANGELOG.md`, rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`, drop the empty
+   - in `CHANGELOG.md`, rename `## [Unreleased]` to `## [vX.Y.Z] - YYYY-MM-DD`, drop the empty
      subsections, open a fresh empty `## [Unreleased]` above it, and update the compare links at
      the foot of the file.
 3. Wait for CI to pass on the merge commit. Then tag that commit and push the tag:
@@ -53,13 +53,12 @@ nothing is written twice.
 Pushing the tag is the release. `.github/workflows/publish-release.yml` then:
 
 1. **Verify** — refuses to continue unless the tag matches `__version__`, `CHANGELOG.md` has a
-   `## [X.Y.Z] - ` section (which becomes the release notes), the tagged commit is on
-   `master`, CI passed on that commit, and the milestone named for the tag, if there is one, has
-   no open items.
+   `## [vX.Y.Z] - ` section (which becomes the release notes), the tagged commit is on
+   `master`, the `ci.yml` workflow passed on that commit, and the milestone named for the tag, if
+   there is one, has no open items.
 2. **Build** — builds the sdist and wheel in an isolated environment, checks their metadata with
    `twine check --strict`, and installs the wheel into a clean virtual environment carrying only
-   the declared runtime dependencies to disassemble a bundled sample with it and run the `smda`
-   entry point.
+   the declared runtime dependencies to disassemble a bundled sample with it.
 3. **Publish** — uploads to PyPI through [trusted publishing](https://docs.pypi.org/trusted-publishers/)
    with signed provenance attestations. No API token is stored anywhere.
 4. **Release** — creates the GitHub release for the tag with the changelog section as its body,
@@ -68,11 +67,16 @@ Pushing the tag is the release. `.github/workflows/publish-release.yml` then:
 
 Each gate fails with a message naming what to fix. Nothing has to be remembered at the console.
 
+The CI gate reads `ci.yml` only. Fuzzing, the security audit and the performance and correctness
+benchmark also run on `master` and are not checked here — the benchmark reports `skipping` on some
+events, and a gate that can never complete is worse than a narrow one — so confirm those by eye
+before tagging, the benchmark above all, since it is the one that catches a recovery regression.
+
 ## Pre-releases
 
 A release candidate is tagged `vX.Y.Zrc1` (also `a1`, `b1`), with the same version string in
 `src/smda/__init__.py` (`__version__`; `pyproject.toml` reads it dynamically and
-`SmdaConfig.VERSION` imports it) and a `## [X.Y.Zrc1] - YYYY-MM-DD` changelog section. The workflow marks the
+`SmdaConfig.VERSION` imports it) and a `## [vX.Y.Zrc1] - YYYY-MM-DD` changelog section. The workflow marks the
 GitHub release as a pre-release and does not make it "latest". PyPI
 does not install a pre-release unless it is asked for explicitly (`pip install --pre`).
 
@@ -83,6 +87,10 @@ through the same gates and build, publishes to [TestPyPI](https://test.pypi.org/
 PyPI (an already-present version is skipped rather than failed), and stops before creating the
 GitHub release. Rehearse the first release after any change to the workflow.
 
+A manual run uses the workflow file as it exists at the chosen tag, so a tag cut before this
+workflow existed has none to run. The first rehearsal needs a tag cut afterwards — a throwaway
+pre-release such as `vX.Y.Zrc0` is enough.
+
 ## When a release fails
 
 - **A gate failed before anything was published** (tag/version mismatch, missing changelog section,

From 466cf7134478f206002112e77d2059cc88056218 Mon Sep 17 00:00:00 2001
From: r0ny123 <49360849+r0ny123@users.noreply.github.com>
Date: Mon, 14 Sep 2026 12:12:13 +0530
Subject: [PATCH 4/4] build(build): keep the 3.11 floor, and write down when it
 moves

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.
---
 .github/workflows/ci.yml              | 22 +++++++++++++---------
 .github/workflows/perf_benchmark.yml  |  6 +++---
 .github/workflows/profile.yml         |  2 +-
 .github/workflows/publish-release.yml |  2 +-
 .github/workflows/security.yml        |  4 ++--
 AGENTS.md                             |  6 +++---
 CHANGELOG.md                          | 13 +++++++------
 README.md                             |  2 +-
 RELEASING.md                          | 20 ++++++++++++++++++++
 pyproject.toml                        |  7 ++++---
 10 files changed, 55 insertions(+), 29 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d44d7947..f2ece5a0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -30,7 +30,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version: "3.11"
           cache: pip
           cache-dependency-path: pyproject.toml
 
@@ -69,12 +69,12 @@ jobs:
         # Linux carries the full interpreter range; Windows and macOS run the floor
         # version only, to catch path/encoding portability without tripling the matrix.
         os: [ubuntu-latest]
-        python-version: ["3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
         include:
           - os: windows-latest
-            python-version: "3.12"
+            python-version: "3.11"
           - os: macos-latest
-            python-version: "3.12"
+            python-version: "3.11"
 
     steps:
       - name: Checkout code
@@ -98,11 +98,11 @@ jobs:
           python -m pip install -e ".[dev]"
 
       - name: Run tests
-        if: matrix.os != 'ubuntu-latest' || matrix.python-version != '3.12'
+        if: matrix.os != 'ubuntu-latest' || matrix.python-version != '3.11'
         run: python -m pytest tests/test*
 
       - name: Run tests with coverage
-        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
         run: |
           set +e
           python -m pytest --cov=smda --cov-branch --cov-report=xml --cov-report=term-missing tests/ 2>&1 | tee coverage-summary.txt
@@ -123,7 +123,7 @@ jobs:
       # Non-blocking for now: full coverage of changed source lines is a policy change,
       # and the metric gets observed over the next few PRs before it holds merges up.
       - name: Check diff coverage
-        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
         continue-on-error: true
         env:
           COMPARE_BRANCH: origin/${{ github.event.repository.default_branch }}
@@ -142,7 +142,7 @@ jobs:
           exit "$status"
 
       - name: Upload coverage report
-        if: always() && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        if: always() && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: coverage-report
@@ -159,12 +159,16 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
         exclude:
+          - os: windows-latest
+            python-version: "3.11"
           - os: windows-latest
             python-version: "3.12"
           - os: windows-latest
             python-version: "3.13"
+          - os: macos-latest
+            python-version: "3.11"
           - os: macos-latest
             python-version: "3.12"
           - os: macos-latest
diff --git a/.github/workflows/perf_benchmark.yml b/.github/workflows/perf_benchmark.yml
index b65fc844..952880e8 100644
--- a/.github/workflows/perf_benchmark.yml
+++ b/.github/workflows/perf_benchmark.yml
@@ -44,7 +44,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version: "3.11"
           cache: pip
           cache-dependency-path: pyproject.toml
 
@@ -119,7 +119,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version: "3.11"
           cache: pip
           cache-dependency-path: pyproject.toml
 
@@ -183,7 +183,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version: "3.11"
 
       - name: Download benchmark runs
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
diff --git a/.github/workflows/profile.yml b/.github/workflows/profile.yml
index 00ce6d9c..7a0069b7 100644
--- a/.github/workflows/profile.yml
+++ b/.github/workflows/profile.yml
@@ -60,7 +60,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version: "3.11"
           cache: pip
           cache-dependency-path: pyproject.toml
 
diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml
index a0e9745d..bc650607 100644
--- a/.github/workflows/publish-release.yml
+++ b/.github/workflows/publish-release.yml
@@ -21,7 +21,7 @@ defaults:
     shell: bash
 
 env:
-  PYTHON_VERSION: "3.12"
+  PYTHON_VERSION: "3.11"
 
 jobs:
   verify:
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
index 45858b69..a222de70 100644
--- a/.github/workflows/security.yml
+++ b/.github/workflows/security.yml
@@ -34,7 +34,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version: "3.11"
           cache: pip
           cache-dependency-path: pyproject.toml
 
@@ -79,7 +79,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version: "3.11"
 
       - name: Install zizmor
         run: |
diff --git a/AGENTS.md b/AGENTS.md
index 949999aa..7776dddd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -90,7 +90,7 @@ Pre-commit hooks (ruff + standard hygiene checks) run on commit via `.pre-commit
 
 ## Code Conventions
 
-- **Formatter / linter:** Ruff. Line length **120**, target **Python 3.12+** (`py312`).
+- **Formatter / linter:** Ruff. Line length **120**, target **Python 3.11+** (`py311`).
 - **Style:** Ruff `select` set is `E4, E7, E9, F, W, I, UP, B, C4, PIE, SIM`. `E501` is ignored (formatter handles length). `UP006`/`UP007` are intentionally ignored to avoid sweeping typing modernization churn.
 - **No comments in code** unless explicitly requested. Keep code self-documenting via clear names and structure.
 - **Imports:** `src`-layout package. Import as `from smda....` (the installed/editable package), never relative path hacks. Ruff's `I` rule enforces import ordering.
@@ -141,7 +141,7 @@ Every other PR writes its own bullet under `## [Unreleased]` as it merges, rathe
 - Mark a test `slow` (`pytestmark = pytest.mark.slow`, or per-test) when it disassembles a real fixture corpus. Marking one keeps the default loop fast; forgetting to mark one is what makes it slow again.
 - Architecture-specific behavior (intel / aarch64 / cil / dalvik) should be covered with representative fixtures where feasible.
 - The xored `tests/*_xored` corpora and the malpedia **benchmark matrix (`.github/workflows/perf_benchmark.yml`) are PR/CI-only** — they require a password-gated malpedia corpus and are not expected to run locally. For local recovery-quality validation, the maintainer works against separate groundtruth datasets rather than the full public matrix. Do not assume you can reproduce the benchmark suite locally.
-- Run tests with `python -m pytest tests/test*` (or `make test`) against a Python 3.12+ environment with the `dev` extra installed.
+- Run tests with `python -m pytest tests/test*` (or `make test`) against a Python 3.11+ environment with the `dev` extra installed.
 
 ## Gotchas
 
@@ -180,7 +180,7 @@ Constraints an agent must respect to avoid breaking SMDA or its downstream consu
 - The feature is **experimental**: it works on well-formed reports but has not been hardened against pathological or adversarial inputs. The golden test fixtures cover one sample per format only.
 - `code_sections` names are **not preserved** through `SmdaReport.toDict()`/`fromDict()` round-trips (they come from LIEF metadata). Tests that mutate a report via `fromDict` must capture VA ranges before the round-trip.
 - Synthesis is deterministic from report content only — it does not consult `STORE_BUFFER`.
-- Install the toolchain with `python -m pip install -e ".[dev]"`; SMDA requires Python 3.12+.
+- Install the toolchain with `python -m pip install -e ".[dev]"`; SMDA requires Python 3.11+.
 
 ### Reality check — common traps for agents
 - **The pipeline description is intel-centric.** The `E8`/`FF 15`/`55 8B EC` heuristics and the gap-search/NOP-list logic belong to the intel backend. Other backends follow their own candidate/traversal logic (e.g. `cil` does essentially no gap search thanks to rich metadata). Do not apply intel assumptions to other architectures.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b9a729e3..1837c41f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -94,13 +94,14 @@ past roughly six lines it belongs in the PR the entry links.
 
 ### Deprecated
 
-### Removed
+- **(build)** Python 3.11 support will end at whichever comes first: MCRIT and purepdb moving their
+  floor to 3.12, a runtime dependency dropping 3.11, or 3.11's end of life in October 2027. SMDA's
+  floor follows MCRIT's and the two move together, because an SMDA that dropped an interpreter MCRIT
+  still declares would be silently held back under MCRIT rather than failing. This affects
+  `smda.ida` users too: IDA 9.3 and 9.4 accept any Python from 3.8 through `idapyswitch`, so an IDA
+  pointed at 3.11 or older will need switching to 3.12 or newer once the floor moves. (#343)
 
-- **(build)** Python 3.11 is no longer supported; `requires-python` is `>=3.12`, and CI runs 3.12
-  through 3.14. Nothing in the engine needed 3.12 — the MCRIT ecosystem now shares a 3.12 floor so
-  one interpreter serves every component. This is not free for IDA users: 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. (#343)
+### Removed
 
 ### Fixed
 
diff --git a/README.md b/README.md
index 4505b851..e65f06d7 100644
--- a/README.md
+++ b/README.md
@@ -191,7 +191,7 @@ Headless export requires IDA 9.1+ and the optional `ida-domain>=0.5.0` dependenc
 
 For Dalvik, the current scope is raw single-DEX inputs (`dex\n`). APK and multi-dex containers are not first-class workflows. ODEX (`dey\n`) and CDEX (`cdex`) are not analysis-compatible (quickened ops / compact `code_item`): with `backend="dalvik"` they raise an explicit error; auto-detect will not select the Dalvik backend for those magics.
 
-The code requires Python 3.12+.
+The code requires Python 3.11+.
 `SmdaReport.metadata.language` is always a score map (`language name -> float`). Internal guesses and evidence
 counters are not serialized; loading an older report normalizes its legacy string/private-key form to this contract.
 To pick a single language from the map, take the highest score, except that `go` and `rust` win outright when their
diff --git a/RELEASING.md b/RELEASING.md
index 6c787987..7687ad64 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -18,6 +18,26 @@ The version is declared in `src/smda/__init__.py` (`__version__`; `pyproject.tom
 `SmdaConfig.VERSION` imports it). The release workflow refuses a tag that does not
 match every one of them, so a bump that misses one fails before anything is published.
 
+## Supported Python versions
+
+SMDA supports Python 3.11 through 3.14, and CI runs every one of them.
+
+The floor follows MCRIT's rather than being set on its own, and the two move in the same release
+wave. An installer resolves a dependency by the interpreter's version, so an SMDA that stopped
+supporting an interpreter MCRIT still declares would be silently held back to its last compatible
+release under MCRIT on that interpreter, with nothing reporting the downgrade.
+
+3.11 support ends at whichever of these comes first:
+
+- MCRIT and purepdb both move their floor to 3.12,
+- a runtime dependency drops 3.11, or
+- 3.11 reaches end of life, in October 2027.
+
+The release that raises the floor says so in its `Removed` section, and the one before it carries
+a `Deprecated` notice. Raising it is not only metadata: Ruff's pyupgrade rules key on
+`target-version`, so the same change starts rewriting syntax to the new floor and stops being
+reversible by a one-line edit.
+
 ## Changelog
 
 `CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). It is the one
diff --git a/pyproject.toml b/pyproject.toml
index 92b2a9d5..b834d8e7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "smda"
 description = "A recursive disassmbler optimized for CFG recovery from memory dumps. Based on capstone."
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.11"
 license = "BSD-2-Clause"
 license-files = ["LICENSE"]
 authors = [
@@ -16,6 +16,7 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
@@ -150,8 +151,8 @@ directory = "coverage-html"
 # Same as Black.
 line-length = 120
 
-# Assume Python 3.12+
-target-version = "py312"
+# Assume Python 3.11+
+target-version = "py311"
 
 [tool.ruff.lint]
 # Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.