Skip to content

RELEASING.md

Latest commit

 

History

History
97 lines (76 loc) · 4.03 KB

RELEASING.md

File metadata and controls

97 lines (76 loc) · 4.03 KB
Raw

Releasing Raven

How a new Raven version is cut and published.

Versioning

  • Semantic versioning MAJOR.MINOR.PATCH. The source of truth is version in pyproject.toml.
  • Tags: vX.Y.Z for a stable release, vX.Y.Z-rcN for a pre-release. The tag must match the pyproject.toml version -- CI enforces this (release.yml).
  • For a pre-release, keep pyproject.toml at the base version (e.g. 0.1.3 while tagging v0.1.3-rc1); CI compares only the base. Do NOT set the version to 0.1.3-rc1 -- that is not a version hatch will build.

Release title

Raven X.Y.Z (YYYY-MM-DD) -- for example Raven 0.1.3 (2026-07-08). The CI draft fills this in automatically (date is the build date; adjust when publishing if needed).

Release notes

Notes are hand-written and curated. The CI draft prefills the boilerplate (Install, Release Status, Notes); a human writes the one-line summary and the Highlights before publishing. Structure:

<one-line summary>

## Highlights
- <user-facing change>

## Install
  install.sh one-liner for Linux / macOS / WSL2
  install.ps1 one-liner for native Windows (plus the PowerShell 5.1 direct URL)
  then: the installer ends on `raven web` (first-run setup is on that page);
  `raven` for the TUI, `raven onboard` to reconfigure

## Upgrade
  raven web --stop, raven upgrade, then raven web once the upgrade has finished,
  with its limits (latest stable unless on the beta channel, plugin wheels
  included, editable checkouts untouched, foreground on POSIX, external helper
  on native Windows)

## Release Status
- Version: `X.Y.Z`
- Tag: `vX.Y.Z`
- Stability: <public preview patch | public preview minor | ...>   # fill by hand per release type
- Assets: wheel, source distribution, the three plugin wheels, locked
  constraints (`raven-constraints.txt`) and the plugin list (`raven-plugins.txt`)

## Notes
- pre-1.0 evolution caveat
- PyPI not enabled; install via the GitHub Release wheel

Stability is not boilerplate -- set it by release type (patch / minor / rc).

Flow

  1. Bump version in pyproject.toml, run uv lock, then open a PR; merge to main.
  2. git tag vX.Y.Z && git push origin vX.Y.Z.
  3. CI (release.yml) builds the wheel + sdist, exports the locked constraints from uv.lock (uv export --locked, which fails the release if the lock is stale vs pyproject), and creates a draft GitHub Release with all three attached, titled and prefilled from the template.
  4. Fill the summary + Highlights in the draft, then click Publish. Publishing makes it /releases/latest, which install.sh serves.

While a release is a draft, GitHub addresses it as releases/tag/untagged-<hash> -- even though the tag already exists, since CI only runs after the tag is pushed. Publishing moves the release to releases/tag/vX.Y.Z and leaves the old URL serving its own stale page with no redirect. So never share the draft URL: a reader who opens it after publication sees "untagged" and concludes the tag is missing or the release never went out. Link releases/tag/vX.Y.Z or /releases/latest instead; the release job prints both URLs in its step summary.

Pre-releases

  • vX.Y.Z-rcN tags build a draft marked pre-release. A pre-release is never /releases/latest, so curl | sh users are unaffected. Use an rc tag to verify the release pipeline before cutting the stable tag; delete the rc release and tag afterward.

Notes

  • main is squash-merge + PR-only. The release itself is not automated past the draft: publishing is a deliberate human step.
  • PyPI publishing is not wired up; the supported install path is the GitHub Release wheel asset resolved by install.sh.
  • install.sh / install.ps1 pass raven-constraints.txt to uv tool install -c, so a one-click install gets the exact locked versions we test rather than re-resolving to the newest allowed by pyproject.toml. A release older than this asset installs without pinning (the scripts degrade gracefully). To lift a pin later, update uv.lock and cut a new release; the install scripts need no change.