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:
Bump the version, and set it everywhere a test holds to it.
Write the CHANGELOG section.
Merge both through a pull request.
Tag the merged commit on
main, and push the tag.Approve the
pypideployment 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 |
|---|---|
|
The latest release: documentation, playground, |
|
|
|
Each released minor version, its highest patch, from 0.8 |
|
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
mainappears 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 itsplayground/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 |
|
The GitHub landing page |
|
The documentation site |
|
The playground |
the header of |
The VS Code extension |
the |
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.