From 3cbd3d4f1889bf6107eaeecea41f2c765e895bd9 Mon Sep 17 00:00:00 2001 From: PRAMOD B N Date: Sat, 15 Aug 2026 16:00:11 -0500 Subject: [PATCH 1/2] docs: split Release checklist into pre-release (branch) and release (main) phases Bumping pyproject.toml/__init__.py/CHANGELOG.md happens on the feature branch, before merge. Tagging and creating the GitHub Release happen on main, after merge -- the previous single flat checklist didn't make that boundary explicit, and also never mentioned creating the GitHub Release at all (only the tag), even though the Releases tab needs a Release object, not just a tag, and release-pypi.yml already listens for both triggers. Also notes --cleanup=verbatim, without which git's default cleanup strips the CHANGELOG's ### headers from the tag message. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 92eeb6b..6111ece 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -197,13 +197,32 @@ 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):** + +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 --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`. +4. Create the GitHub Release: `gh release create vX.Y.Z --title vX.Y.Z + --notes-file `. A pushed tag alone does **not** appear in + the Releases tab — this step is what does, and it's easy to skip since + nothing in step 3 fails without it. + +`release-pypi.yml` triggers on *both* the tag push (step 3) and the +Release being published (step 4), 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. Doing both steps 3 and 4 means the workflow runs +twice; that's expected, not a bug — PyPI accepts the second, identical +upload as a no-op. From 7ab2a506eda390818ec088ee10857d20af8a1ee7 Mon Sep 17 00:00:00 2001 From: PRAMOD B N Date: Sat, 15 Aug 2026 16:02:12 -0500 Subject: [PATCH 2/2] docs: drop gh CLI from the release step, plain git tag+push is sufficient release-pypi.yml already triggers on the tag push alone -- gh release create was an extra, non-git-only step. Note the tradeoff explicitly: skipping it means the Releases tab stays empty unless someone creates one by hand later, which is accepted here rather than automated. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6111ece..e513dd0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -205,7 +205,8 @@ and releasing happen after: (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):** +**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, @@ -214,15 +215,15 @@ branch's normal history; goes in with the rest of the PR. `--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`. -4. Create the GitHub Release: `gh release create vX.Y.Z --title vX.Y.Z - --notes-file `. A pushed tag alone does **not** appear in - the Releases tab — this step is what does, and it's easy to skip since - nothing in step 3 fails without it. - -`release-pypi.yml` triggers on *both* the tag push (step 3) and the -Release being published (step 4), 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. Doing both steps 3 and 4 means the workflow runs -twice; that's expected, not a bug — PyPI accepts the second, identical -upload as a no-op. + +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.