From e4188f5222f69185bf27bd22568bec15b5ea99ca Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Thu, 28 May 2026 17:56:23 +0700 Subject: [PATCH] Document the two-step release flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The release has two steps: preparation, which the agent does locally and reversibly, and go-ahead, which only the user authorizes. Last-minute changes always need approval, code changes never bundle into the changelog or release commit, and a sanity-check finding is information for the user — not a directive for the agent to act on. --- docs/release.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/release.md b/docs/release.md index 19dfdd87b..d53dca9e7 100644 --- a/docs/release.md +++ b/docs/release.md @@ -2,6 +2,29 @@ All workspaces share one version and release together. +## Two steps + +A release has exactly two steps. The agent does the first, the user authorizes the second. + +**Preparation** (local, reversible — agent does this): + +- format, lint, typecheck all green +- draft the changelog, show it to the user, wait for review +- run the pre-release sanity check, surface findings to the user +- confirm CI is green + +**Go-ahead** (user says "go ahead"): + +- commit the approved changelog +- run the release + +Rules that apply to both steps: + +- Last-minute changes always need approval. Every time. +- No code changes bundled into the changelog commit or the release commit. Code shims live in their own commit, reviewed on their own merits. +- A sanity-check finding is information, not a directive. The agent surfaces it; the user decides. +- Invoking a release skill is intent to start the flow, not blanket authorization to publish. + ## Two paths There are two supported ways to ship from `main`: