release

/release

Publish a new version of everos to PyPI. Publishing is automated: pushing a

vX.Y.Z tag triggers [.github/workflows/release.yml](../../../.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.

1. 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.