/release

Publish a new version of everos to PyPI. Publishing is automated: pushing a vX.Y.Z tag triggers .github/workflows/release.yml, which builds, smoke-tests, and uploads via PyPI Trusted Publishing (OIDC — no stored token) behind the release environment's manual-approval gate, then drafts the GitHub Release page from the CHANGELOG.

A release is not finished when PyPI accepts the upload: the GitHub Release page is drafted, never auto-published, and someone has to write its lead summary and click Publish.

Preconditions

• On main, up to date, with green CI (the tag builds from main's tree).
• Decide the version per SemVer: patch = fixes, minor = back-compatible features, major = breaking changes.

Steps

1. Bump the version    → pyproject.toml [project] version = "X.Y.Z"
   (single source; everos.__version__ reads installed package metadata)
2. Update CHANGELOG.md → move the Unreleased entries under a new
   ## [X.Y.Z] - <date> heading, and write the release page's prose here
   (lead paragraph + `### Upgrade` group — see "The release page")
3. Commit              → git commit -m "chore(release): vX.Y.Z"
4. Open a PR, merge to main after green CI
5. Tag main + push     → git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
6. Approve             → the release.yml run pauses on the `release`
   environment; a reviewer approves in the Actions run
7. Verify              → https://pypi.org/project/everos/X.Y.Z/
8. Publish the page    → the run leaves a DRAFT GitHub Release, already
   complete if step 2 was done properly. Read it once, click Publish.

The tag must equal the pyproject.toml version — the workflow refuses to publish on a mismatch. A stable tag with no matching ## [X.Y.Z] CHANGELOG section fails the release job for the same reason.

The release page

The whole page is written in CHANGELOG.md, during the release PR. Nothing is meant to be composed at publish time — by then the changes are weeks old and the text gets no review. Write the version section like this:

## [X.Y.Z] - 2026-09-01

**What this release is for.** One paragraph, prose, no bullets — it becomes the
lead of the release page. Say what changed for a user, not what was refactored.

### Added
### Changed
### Fixed

### Upgrade

What a reader must know before upgrading: what happens on first startup, which
command recovers a bad state, which pins moved. Omit the group entirely when a
plain `pip install --upgrade` is all there is — 1.1.4 and 1.2.0 have nothing
here. Do not write filler.

CI turns that into the page: everything above ### Upgrade is lifted verbatim with the group headings demoted to ##, and the Upgrade prose is wrapped in the boilerplate — pip line above it, compare link below — which is the shape every release since 1.1.3 has. See 1.2.1.

So publishing is a read-through and a click. If the draft looks wrong, the fix belongs in CHANGELOG.md on main, not only in the draft — otherwise the two drift apart and the next release inherits the habit.

While it is a draft, GitHub serves the release at releases/tag/untagged-<hash>, and that URL keeps serving a stale page after publication with no redirect. Never share it — a reader who opens it later concludes the release never went out. Link releases/tag/vX.Y.Z instead; the job prints both URLs in its step summary.

Publish with the Publish release button in the web UI. Publishing through the API by flipping draft alone drops the tag: GitHub rebinds the release to the untagged-<hash> placeholder and creates a git tag by that name against the default branch (observed on 1.2.2). Pass tag_name if you must do it from the CLI:

gh api -X PATCH "repos/EverMind-AI/EverOS/releases/<id>" \
  -F draft=false -f tag_name=vX.Y.Z -f make_latest=true

Re-running the release job replaces its own draft and leaves an already-published release untouched, so a re-run is always safe.

Pre-releases

PEP 440 pre-release tags publish too (PyPI accepts them; pip install everos ignores them unless --pre): vX.Y.ZrcN, vX.Y.ZaN, vX.Y.ZbN. Set the same suffix in pyproject.toml version before tagging.

Their release page is drafted as a pre-release and never becomes /releases/latest. A pre-release does not need its own CHANGELOG section — the draft falls back to a one-line placeholder body when there is none.

One-time setup (project owner, not doable from CI)

1. PyPI trusted publisher — PyPI → project everos → Settings → Publishing → add: owner EverMind-AI, repo EverOS, workflow release.yml, environment release.
2. GitHub environment — repo Settings → Environments → create release with required reviewers, so every publish needs a manual approval.

No PyPI API token is ever stored; the workflow mints a short-lived OIDC token at publish time.