Skip to content

docs: split Release checklist into pre-release/release phases #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pramodbn27 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: split Release checklist into pre-release/release phases #6

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3cbd3d4
docs: split Release checklist into pre-release (branch) and release (…
pramodbn27 Aug 15, 2026
7ab2a50
docs: drop gh CLI from the release step, plain git tag+push is suffic…
pramodbn27 Aug 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 30 additions & 10 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,13 +197,33 @@ Run `make check` before every push. It runs: lint → format-check → typecheck

## Release

1. Bump version in `pyproject.toml`, `src/agentic_sidecar/__init__.py`, and `CHANGELOG.md`
2. Commit: `git commit -am "release: vX.Y.Z"`
3. Tag: create an annotated `vX.Y.Z` tag and use the latest `CHANGELOG.md`
release section as the tag description
4. Push: `git push origin main --tags`

The `release-pypi.yml` workflow triggers on the tag push and publishes to
PyPI via Trusted Publishing (OIDC) — no API token/secret required, but the
`pypi` GitHub Environment must exist and be configured as a Trusted
Publisher on PyPI before the first release.
Two phases, split by the merge to `main` — bumping happens before, tagging
and releasing happen after:

**1. Pre-release (on the feature branch, before merge):** Bump version in
`pyproject.toml`, `src/agentic_sidecar/__init__.py`, and `CHANGELOG.md`
(a dated release section under `[Unreleased]`). Commit as part of the
branch's normal history; goes in with the rest of the PR.

**2. Release (on `main`, once that branch has merged):** plain `git`, no
`gh` CLI required.

1. Pull the merge commit on `main`.
2. Tag: create an annotated `vX.Y.Z` tag pointing at the merge commit,
using the CHANGELOG's release section as the tag message:
`git tag -a vX.Y.Z -F <file-with-that-section> --cleanup=verbatim`.
`--cleanup=verbatim` is required — git's default cleanup silently strips
lines starting with `#`, which would eat the CHANGELOG's `###` headers.
3. Push the tag: `git push origin vX.Y.Z`.

That's the whole release: `release-pypi.yml` triggers on the tag push and
publishes to PyPI via Trusted Publishing (OIDC) — no API token/secret
required, but the `pypi` GitHub Environment must exist and be configured
as a Trusted Publisher on PyPI before the first release.

Note this deliberately does not create a GitHub Release object (that's a
`gh`/API-only action, not a `git` one) — the tag alone is enough to
publish to PyPI, but it means the repo's Releases tab stays empty unless
someone creates one by hand later (GitHub UI: Releases → Draft a new
release → pick the existing tag). That's an accepted tradeoff here, not
an oversight.