Releasing#

A release is a git tag. Everything else follows from it automatically.

That is not a Scenet invention: a GitHub Release is by definition metadata attached to a tag, and the Python Packaging Authority’s own publishing guide triggers on exactly this. The tag is the single source of truth.

Cutting a release#

A release is a pull request, a tag and one click:

  1. Bump the version, and set it everywhere a test holds to it.

  2. Write the CHANGELOG section.

  3. Merge both through a pull request.

  4. Tag the merged commit on main, and push the tag.

  5. Approve the pypi deployment when the release run asks.

The version first:

uv version --bump minor

major, minor or patch. This edits project.version in pyproject.toml and nothing else. Check what it will do first with --dry-run.

Set the same version in server.json, in both places it appears — the MCP registry manifest has to name the release it points at, and a test fails until it does.

Set it too as version in editor/package.json, and run npm install --package-lock-only in editor/ to carry it into the lockfile. The extension shipped with a release is versioned as that release, and a test fails until both files agree with pyproject.toml.

Set it too in Build and check a comic in CI, as the scenet== pin its workflow installs and the release it was last checked with: a test fails until both name the version in pyproject.toml.

For a new minor version, set the supported row in SECURITY.md to it: 0.13.x for 0.13.0. Fixes go to the latest minor release, and a test fails until the policy names the one pyproject.toml does.

Then write the changelog section. CHANGELOG.md follows Keep a Changelog; rename the ## [Unreleased] heading to ## [0.2.0] - 2026-08-23 and start a fresh Unreleased above it.

Write it for people. These become the release notes verbatim. A list of commit subjects is not release notes — it is a list of commit subjects.

main is protected, so the version bump and changelog go through a pull request like anything else:

git switch -c release/0.2.0
git commit -am "chore: release 0.2.0"
git push -u origin release/0.2.0
gh pr create --fill && gh pr checks --watch
gh pr merge --squash --delete-branch

Then tag the merged commit on main:

git switch main && git pull
git tag -a v0.2.0 -m "scenet 0.2.0"
git push origin v0.2.0

Pushing the tag is what starts everything. Tag only a green main — the release workflow re-runs every gate anyway, but discovering a failure after the tag exists means deleting a tag, and v* tags are protected against exactly that.

Nothing about the package itself should surprise you at this point: every pull request already builds the sdist and the wheel, checks with twine check --strict that PyPI can render the description, runs the same wheel smoke test as the release (scripts/smoke_wheel.py), and builds the wheel again from the sdist alone. That is CI’s Package job.

What happens next#

push tag v0.2.0
      │
      ├─ verify    tag == project.version?
      │            CHANGELOG has a [0.2.0] section?
      │            format, lint, types, full test suite
      │
      ├─ build     uv build → sdist + wheel
      │            install the wheel in a clean environment and exercise it
      │
      ├─ extension npm ci → tsc → vsce package → scenet.vsix
      │
      ├─ site      the documentation and the playground, running the wheel
      │            `build` made → scenet-0.2.0-site.zip
      │
      ├─ publish   ⏸ waits for you to approve the `pypi` environment
      │            → pypi.org, via Trusted Publishing, with attestations
      │
      ├─ release   → GitHub Release, notes from CHANGELOG,
      │              sdist + wheel + vsix + site attached
      │
      └─ registry  → listed in the MCP registry, from the PyPI package

then, once the run completes:

      Pages        → the site's root serves the release; /vX.Y/ holds it too

For this repository, all of it is switched on: PyPI publishing, the approval before it, and the registry listing. So a release is the pull request, the tag, and one click to approve – nothing else is done by hand. The sections below say how each switch works and how to turn it off.

Everything that can fail runs before anything is published. PyPI never allows re-uploading a version — not after a delete, not ever — so a half-finished release burns that number permanently. The verify job exists to make that impossible.

You will get an email when the run reaches publish. Open it, click Review deployments, tick pypi, Approve and deploy. That click is the last gate between a tag and PyPI.

Removing that gate#

The approval is a required reviewer on the pypi GitHub Environment, not anything in the workflow file. It can be removed, and the release then runs unattended from the tag:

gh api -X PUT repos/creatoan/scenet/environments/pypi   --input - <<'JSON'
{"wait_timer": 0, "reviewers": null, "deployment_branch_policy": null}
JSON

What you give up. PyPI never allows re-uploading a version — not after a delete, not ever — so an accidental or mistaken tag burns that number permanently, and the click is what makes a tag reversible right up to the last moment. What you keep is not nothing: verify still runs format, lint, types and the full suite before anything is published, the tag must match project.version, the CHANGELOG must have a section for it, and v* tags are protected against deletion.

It is a real trade. Releases stop being synchronous, which matters when the person who tagged is not around to approve; and the gate protects against a mistake that cannot be undone. Decide once, deliberately, rather than discovering it mid-release.

The site attached to each release#

Every release carries its documentation site, built by the site job: the documentation, the playground running the very wheel PyPI gets, the JSON Schemas, the spec pack and llms.txt, as scenet-X.Y.Z-site.zip on the GitHub Release. It is built before anything is published, so a documentation build that fails (sphinx -W) stops the release while nothing is out yet.

That attachment is the one build of the release’s site there will ever be. The documentation site serves every version from the attachments, so the site of a version is exactly what was released, whatever has changed since. Anyone can also download it to read offline; the playground in it needs a local web server, not file://.

What the site serves#

Path

What

/scenet/

The latest release: documentation, playground, schemas/, scenet-spec.md, llms.txt

/scenet/dev/

main, rebuilt on every push

/scenet/vX.Y/

Each released minor version, its highest patch, from 0.8

/scenet/switcher.json

The version switcher’s data, which every version reads

pages.yml builds main, downloads the site attached to each release, and assembles them (scripts/build_site.py). It runs on every push to main, which changes /dev/ and nothing else, and when the release workflow completes, which moves the root to the new release. Run it by hand (Actions → Pages → Run workflow) after a backfill, or after deleting a release’s site:

gh workflow run pages.yml

Some consequences worth knowing:

  • A documentation fix merged to main appears under /dev/ only. The root changes when a release does. To correct the documentation of a release people are using, cut a patch release: /vX.Y/ and the root then serve it.

  • Only the three newest minor versions keep their playground, besides the root and /dev/. An older version keeps its documentation, schemas and spec pack, and its playground/ becomes a page pointing at the latest playground and at the full site on the release. GitHub Pages caps a site at 1 GB; the assembly fails before it gets there.

  • Every page names its counterpart at the root as canonical, so search engines send readers to the current documentation.

To look at the site as it will deploy, build it and serve it locally — under /scenet/, as Pages does, which the version switcher needs:

uv run python scripts/build_site.py
uv run python scripts/serve_site.py

That downloads the releases’ sites with gh, so it must be signed in. With --releases DIR it takes them from a directory instead, such as the one backfill_site.py writes to.

Backfilling a release made before that#

Releases up to 0.11.0 were made before releases carried a site. Actions → Site backfill → Run workflow, giving the tag, builds one and attaches it:

gh workflow run site-backfill.yml -f tag=v0.11.0

It builds the release’s own sources with its own lockfiles, and its playground runs the wheel attached to that release. Only the files that make a build versioned (backfill_site.py lists them) are taken from main and laid over the release’s. That is sound only where the release built its site with the same tooling as v0.11.0, which holds from v0.8.0 to v0.11.0; the script refuses any other tag. The documentation of v0.1.0 to v0.7.0 is not on the site, and stays readable at its tag on GitHub.

The workflow never replaces a site already attached. To rebuild one, delete the asset from the release first. The same build runs locally, without attaching anything:

uv run python scripts/backfill_site.py v0.11.0 --out build/backfill

If immutable releases are ever enabled for this repository, a published release can no longer gain an asset, and backfilling stops being possible. Releases made by the workflow are unaffected: their site is attached as they are created.

Listing in the MCP registry#

Automatic, as the release workflow’s last job, once PyPI has the release. The official MCP registry stores metadata only: server.json describes how to launch scenet mcp from the PyPI package, and the registry checks that the package’s description — the README — carries the mcp-name marker for the io.github.creatoan/scenet namespace.

This is done by a workflow, not from a laptop. mcp-publisher login github — the interactive login — fails for an organisation namespace: the registry’s GitHub App is not installed on the organisation, so the registry sees only io.github.<your-user>/* and answers 403 for io.github.creatoan/*, whatever the role and whatever the membership visibility. That is an open upstream bug reported by several people (#1468, #1537, #1649). The workflow, .github/workflows/registry.yml, logs in the other way the registry supports — GitHub’s OIDC token, which proves the namespace through the repository it runs in — and needs no secret.

release.yml calls that workflow after the GitHub Release, because the repository variable MCP_REGISTRY_PUBLISH is true. It was switched on once a hand run had listed 0.9.0, which proved the login works for this namespace, and 0.10.0 was the first release listed by the release itself. There is nothing to do for the registry when you release.

Nothing waits on it: a failed listing leaves a complete release behind. Run it by hand only to retry one that failed, or to list a release cut while the variable was unset: Actions → MCP Registry → Run workflow, giving the tag (v0.10.0). Check the release run first: when its List in the MCP registry job passed, the version is listed and there is nothing to retry.

To stop listing releases, delete the variable; release.yml then skips the job:

gh variable delete MCP_REGISTRY_PUBLISH

The workflow checks that server.json names the tag’s version and that the version is on PyPI, then runs mcp-publisher validate, login github-oidc and publish. publish has no dry-run flag: an unknown flag is ignored, so publish --dry-run publishes. Use validate, which checks the manifest against the live registry and changes nothing.

mcp-publisher is pinned to a version and a SHA-256 in the workflow, because it runs with the credential in reach. To update it, download the new linux_amd64 tarball, check it, and replace both values.

A listing can be withdrawn. mcp-publisher status --status deprecated|deleted <name> <version> (or --all-versions) changes a version’s status, with an optional --message.

PyPI is opt-in#

The publish job is skipped unless the repository variable PYPI_TRUSTED_PUBLISHER is true. It is, for this repository; this section is how it was set up, and what happens without it:

gh variable set PYPI_TRUSTED_PUBLISHER --body true

That exists because a trusted publisher has to be registered through a web form on pypi.org – there is no API, deliberately, since it is the thing that grants publishing rights. Until somebody has done that, the job cannot succeed, and gating it on an explicit switch is better than every release failing on a step nobody enabled.

A release still happens without it. The GitHub Release is created either way, with the sdist, the wheel and the .vsix attached, and the notes say to install from the wheel URL rather than claiming a pip install scenet that would not work. The release is only blocked if PyPI is enabled and fails – announcing a version whose upload broke halfway would be worse than not announcing it.

Rehearsing first#

Before the first real release, or any release you are nervous about, run the TestPyPI rehearsal workflow from the Actions tab. It publishes to test.pypi.org — a throwaway instance of the same software, periodically wiped — and then installs the result back in a clean environment to prove the artifact works.

TestPyPI also refuses duplicate versions, so pass a dev1, dev2… suffix when you re-rehearse the same version.

If something goes wrong#

The tag does not match project.version. verify fails before anything is published. Delete the tag, fix, re-tag:

git tag -d v0.2.0 && git push origin :refs/tags/v0.2.0

Published to PyPI, then found a bug. You cannot replace it. Yank the release on PyPI — which hides it from new installs while leaving it available to anyone who pinned it — and release a patch version. Yanking is the recovery mechanism; deleting is not.

The GitHub Release step failed after PyPI succeeded. The package is out. Re-run just that job from the Actions tab; it is idempotent apart from the release already existing.

The AI-generation disclosure is a release requirement#

Every published surface must carry the statement that this project is deliberately AI-generated. Not as a courtesy — as a condition of publishing. Anyone who finds the package on PyPI, installs the extension, or opens the playground is entitled to know what they are looking at before they decide to rely on it.

Surface

Where it comes from

The PyPI project page

README.md, via readme = "README.md"

The GitHub landing page

README.md

The documentation site

docs/index.md

The playground

the header of playground/index.html

The VS Code extension

the description in editor/package.json, and editor/README.md

tests/test_disclosure.py checks all of them, and checks that the README’s disclosure is above the fold and is a heading rather than a footnote. It is tested rather than trusted because it is exactly the kind of thing that quietly disappears: somebody rewrites a description, trims a README, restructures a page, and it goes with them. Nobody notices, because nothing was watching.

Adding a new published surface means adding it to that test. A new marketplace listing, a new landing page, a package on another index — each is a place a stranger can arrive without having read anything else.

Versioning#

Semantic versioning, applied to two things:

  • The Python API — everything in scenet.__all__. Names outside it are internal and may change in a minor release.

  • The language — a construct that stops compiling is a major change. New optional keys are minor.

format_version inside a Panel Core document is separate, and bumped only when the shape of that document changes incompatibly.

While the version is below 1.0.0, minor versions may break things. That is what being below 1.0 means, and the status is alpha for a reason.

What is not automated, deliberately#

Nothing decides on its own that a release should happen. There is no bot reading commit messages and opening a release pull request.

That is a choice. Conventional-commit automation trades a small amount of typing for a strict format on every commit message forever, and for a project of this size the arithmetic does not work out. Deciding that a release is worth making is a judgement, and it is a cheap one to make by hand.