release-workflow · diff
v0.1.0 to v0.3.0
70 added, 44 removed. Audit A to A.
---
name: release-workflow
- description: Release cycle conventions including CHANGELOG format, README maintenance, version bumping, and git workflow.
- version: 0.1.0
+ description: Release cycle conventions for Savant-Code pipeline releases
+ version: 0.3.0
+ metadata:
+ origin: agent
---
- # Release Workflow Standards
-
- <!-- Load this for all projects — defines the mandatory release cycle -->
+ # Release Workflow Standards (Savant-Code)
- ## Mandatory Release Cycle
+ ## When to Use
- Every time code is pushed:
+ <!-- Load this for all projects — defines the mandatory release cycle -->
- 1. **Update CHANGELOG.md** — add entries for all changes since last push
- 2. **Review README.md** — update test counts, version references, any stale data
- 3. **Commit docs** — `git add CHANGELOG.md README.md && git commit -m "docs: ..."`
- 4. **Push** — `git push`
- 5. **Create/update release** — tag + release notes on GitHub (or equivalent)
+ For any version bump, release, resume, or release-readiness check in
+ Savant-Code. Releases flow exclusively through the public-release pipeline
+ (`scripts/public-release.ts`; docs: `docs/public-release.md`).
- **Never push code without updating CHANGELOG + README first. Never skip the release.**
+ ## Procedure
- ## CHANGELOG Format
+ 1. **Open the version heading at bump time** — when the version bump lands
+ (`bun run version:bump`), open `## <version> — <YYYY-MM-DD>` in
+ `CHANGELOG.md` and write release notes directly beneath it as each change
+ closes. **Never accumulate an `## Unreleased` section** — the release
+ engine (`extractChangelogSection`) requires exactly one version heading
+ matching the release version; Unreleased content never ships in notes.
+ 2. **Audit phase before push** — run the gate battery and fix everything red:
+ `bun run typecheck` (all workspaces), `bun run test`,
+ `bun x eslint . --max-warnings 0`, `bun run lint:md`,
+ `bun run validate:repository`, `bun run version:check`, plus the
+ generated-doc drift checks (`generate:provider-docs:check`,
+ `generate:protocol-bundle:check`).
+ 3. **Preview** — `bun run release:public:preview` (read-only plan: identity,
+ version metadata, CHANGELOG section extraction; never mutates).
+ 4. **Diagnose** — `bun run release:public:diagnose` (read-only full gate
+ manifest with evidence; investigate failures here).
+ 5. **Release** — `SAVANT_CODE_RELEASE_AUTOMATION=1 bun run release:public`
+ (automation) or interactive `bun run release:public`. The engine commits,
+ tags, pushes main + tag, creates the GitHub release from the extracted
+ changelog section, and publishes the scoped npm packages (default
+ CLI-only; SDK opt-in via `SAVANT_CODE_RELEASE_PACKAGES`).
+ 6. Failure mid-transaction → fix the cause, then
+ `bun run release:public:resume` with the same package scope.
- Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/):
+ **Never push code without the version heading + notes in CHANGELOG.md and the
+ README checked against the release. Never release outside the pipeline.**
- ```markdown
- ## [VERSION] — YYYY-MM-DD
+ ### CHANGELOG format
- ### Added
- - New features
+ One reverse-chronological heading per released version — no brackets, no
+ Keep-a-Changelog category scaffolding, no `## Unreleased`:
- ### Fixed
- - Bug fixes
+ ## 0.0.30 — 2026-09-08
- ### Changed
- - Modifications to existing behavior
+ ### <Area heading> (closed YYYY-MM-DD)
- ### Removed
- - Deprecated features
- ```
+ - **FID-2026-0907-00X — severity — summary.** Details with file references.
Group entries by FID when applicable. Include file references in parentheses.
- ## README Maintenance
+ ### Version bumping
- On every release, verify:
+ - **Patch** (0.0.29 → 0.0.30): fixes, small improvements
+ - **Minor** (0.0.x → 0.1.0): new features, non-breaking changes
+ - **Major** (0.x → 1.0.0): breaking changes, architecture shifts
- - [ ] Version number matches Cargo.toml / package.json
- - [ ] Test count matches `cargo test` output
- - [ ] FID count matches `dev/fids/` directory
- - [ ] All referenced features still exist
- - [ ] No stale links or descriptions
+ Run `bun run version:bump` — it updates `VERSION` and propagates to every
+ manifest (verify with `bun run version:check`). Open the matching CHANGELOG
+ version heading in the same change.
- ## AGENTS.md
+ ## Pitfalls
- Each project should have an `AGENTS.md` at the root with:
+ - Accumulating an `## Unreleased` section — the engine requires exactly one
+ version heading matching the release, so it never ships.
+ - Bumping without opening the CHANGELOG heading in the same change.
+ - Running the release without the audit phase, or pushing first and auditing
+ after: `release:preaudit:check` treats a dirty worktree as blocking.
+ - Bumping the version token and hand-editing the `> **vX.Y.Z**` release callout
+ in `README.md` / `README.zh-CN.md`. Only the token is single-sourced; the
+ callout body is hand-written and drifts.
- - Project-specific release workflow (may override this standard)
- - Build & test commands
- - Protocol version reference
- - Any project-specific conventions
+ ## Verification
- ## Version Bumping
+ On every release, verify:
- - **Patch** (0.1.0 → 0.1.1): Bug fixes, small improvements
- - **Minor** (0.1.0 → 0.2.0): New features, non-breaking changes
- - **Major** (0.1.0 → 1.0.0): Breaking changes, architecture shifts
+ - [ ] Version references match `VERSION` (single-sourced via `version:bump`)
+ - [ ] Test counts and provider/feature lists match the tree
+ - [ ] FID references resolve (active queue + archive)
+ - [ ] No stale links or descriptions
- Update `VERSION` file first, then propagate to all config files.
+ Then confirm the read-only legs agree before mutating anything:
+ `bun run release:public:preview` and `bun run release:public:diagnose` must
+ both report the extracted CHANGELOG section matching the bumped version.
+
+ The repository root carries `AGENTS.md` with project-specific overrides
+ (release workflow, build/test commands, protocol version, conventions).