Skip to content

RELEASE_PROCESS.md

Latest commit

 

History

History
110 lines (85 loc) · 4.17 KB

RELEASE_PROCESS.md

File metadata and controls

110 lines (85 loc) · 4.17 KB
Raw

Release process

Audience: whoever is cutting the next tag. This is the step-by-step checklist. Run the /release <version> slash command for a guided walkthrough that follows the same steps.

llmwiki uses semantic versioning with a pre-1.0.0 caveat: every 0.x.y release can break compatibility freely. 1.0.0 will be the first stable release.

Minor-version bumps (0.X.0) ship when a coherent feature batch lands (heatmap + tool chart + token usage = v0.8). Patch bumps (0.X.y) ship when a critical fix can't wait for the next minor.

Pre-flight

  • Master is green (all tests pass, all recent CI runs passed)
  • python3 -m pytest tests/ -q on a clean checkout — local pass beats CI-only pass
  • python3 -m llmwiki build succeeds end-to-end, no warnings that weren't there before
  • Preview the built site locally and click through every nav item — look for broken links, missing icons, crashed JS
  • No open priority:critical bugs (run gh issue list --label priority:critical --state open and verify it's empty)

Bump version

The single source of truth is llmwiki/__init__.py. Every other place that mentions the version is derivative and must match.

  • Update __version__ = "X.Y.Z" in llmwiki/__init__.py
  • Update version = "X.Y.Z" in pyproject.toml (the test test_pyproject_version_matches_package enforces this)
  • Update the version badge in README.md (Version-vX.Y.Z-7C3AED.svg)
  • Update the tests badge in README.md with the new passing count from python3 -m pytest tests/
  • Run python3 -m llmwiki --version and confirm it prints the new version

Update CHANGELOG

  • Move every entry from ## [Unreleased] into a new ## [X.Y.Z] — YYYY-MM-DD section
  • Re-create an empty ## [Unreleased] section above the new one
  • Group entries by ### Added / ### Changed / ### Fixed / ### Removed in keep-a-changelog order
  • Add a one-line "Theme:" at the top of the release section summarising the batch (e.g. "Theme: v0.8 visualization trio — heatmap, tool charts, token usage")
  • Spot-check every PR number against the actual merged PRs — copy-paste errors happen

Commit + tag

git add llmwiki/__init__.py pyproject.toml README.md CHANGELOG.md
git commit -m "release(vX.Y.Z): bump version + CHANGELOG"
git tag vX.Y.Z
git push origin master vX.Y.Z
  • Do NOT force-push master
  • Do NOT amend the release commit after tagging

GitHub Release + PyPI publish

The tag push triggers .github/workflows/release.yml which automatically:

  1. Builds sdist + wheel via python -m build
  2. Publishes to PyPI via OIDC trusted publisher (no API tokens needed)
  3. Signs artifacts with Sigstore
  4. Creates a GitHub Release with build artifacts + signature bundles
  • Confirm the release workflow ran: gh run list --workflow=release.yml --limit=3
  • Confirm the package is on PyPI: pip install llm-notebook==X.Y.Z
  • Confirm the release shows up at https://github.com/Pratiyush/llm-wiki/releases
  • If the workflow failed, check the "release" environment protection rules

Manual fallback (if automation is broken):

gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes --prerelease

Verify Pages deploy

  • .github/workflows/pages.yml fires on both master push and the new tag. Watch the run with gh run list --workflow=pages.yml --limit=3
  • Visit https://pratiyush.github.io/llm-wiki/ and confirm the new version badge + any new features are visible
  • If the deploy failed, fix master first; don't hotfix the tag

Announce (optional)

  • Post to the project X account / LinkedIn with a link to the GitHub Release page
  • Pin an "issue digest" discussion thread with the highlights if it's a milestone release (v0.5, v0.9, v1.0, ...)

Rollback

If a release is broken, don't delete the tag. Do:

  1. Cut a patch release (vX.Y.Z+1) that reverts the bad PR
  2. Mark the broken release as "Pre-release" and edit the notes to say "superseded by vX.Y.Z+1"
  3. Never delete tags — downstream packages may pin to them