From 849f67b0cf5f703356ff200252f1dc487ba50332 Mon Sep 17 00:00:00 2001 From: Sal Date: Thu, 3 Sep 2026 04:15:14 +0100 Subject: [PATCH] docs(contributing): document release authorization and repair the fences #468's remaining acceptance criterion was to document the signed tag as the sole publication authorization. Everything else it asks for already shipped with #470 and #497: the organization release-prepare caller, the tag-triggered workflow with explicit permissions and non-cancelling concurrency, the twelve rejection checks in scripts/verify-release-tag.zsh, no stored version file, and tests/release-tag-verification.zsh under actionlint and YAML validation. Add a Releases section covering the proposal, the maintainer-pushed signed tag, each condition the verifier enforces, and the fact that ZI[VERSION] is derived from `git describe' so the tag is the version. Also repair the code fences in the same file. The first fence opened with four backticks and the fence that appeared to close it had three plus an info string, which cannot close it. The real closer was a stray four-backtick line at the end of the file, so lines 7 to 69 rendered as a single code block: the commit-message format, what-not-to-add and discussion sections were all displayed as preformatted text rather than markdown. Fifty-eight lines were swallowed; the file now renders fifteen lines as code, which is the four intended blocks. Found while looking for where release authorization was documented. Not previously reported. Closes #468 --- docs/CONTRIBUTING.md | 42 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4dd3d24..2853c7b 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -4,7 +4,7 @@ Thank you for contributing! Please follow the guidelines below to keep the proje ## Branch model -````text +```text main production and consumable ref |-- hotfix- urgent fixes that may target main ^ @@ -12,7 +12,7 @@ next integration branch; ordinary PRs target here ^ |-- feature- new features `-- bug- bug fixes -```text +``` 1. Branch ordinary work from `next`: `git switch -c bug-123 next`. 2. Target `next` from `feature-` and `bug-` branches. @@ -38,7 +38,7 @@ Wrap at 72 characters. Optional footer(s): Fixes #123 BREAKING CHANGE: description of what breaks -```text +``` **Allowed types:** `feat` `fix` `perf` `refactor` `docs` `test` `ci` `chore` `revert` @@ -55,6 +55,41 @@ Repository rules intentionally omit linear-history requirements on both persistent branches so promotion and hotfix synchronization can preserve their merge commits. +## Releases + +A promotion to `main` publishes nothing. It updates the Git-consumed stable ref +and stops there. + +**A signed annotated tag is the sole publication authorization.** Nothing else +creates a release: not a merge, not a green pipeline, not the automated +proposal. + +1. After a promotion reaches `main`, `Release Prepare` opens or updates a + proposal issue with the next semantic version computed from Conventional + Commits and a draft changelog. It never creates a tag. +2. A maintainer reviews the proposed version, adjusts it if the computed bump + does not describe the change, and pushes a signed annotated tag: + + ```text + git switch main && git pull --ff-only + git tag -s vX.Y.Z -F + git push origin vX.Y.Z + ``` + +3. `scripts/verify-release-tag.zsh` rejects the tag unless every one of the + following holds: it matches `vX.Y.Z`, it is annotated rather than + lightweight, GitHub reports its signature as verified, its target is the + current `origin/main`, and the `Zsh`, `ZD Integration`, `CodeQL` and + `Trunk Code Quality` workflows all succeeded on that exact commit. +4. Only then is a GitHub release published, idempotently, with generated notes. + +The repository stores no version file. `ZI[VERSION]` is derived at runtime from +`git describe --tags --exact-match`, so the tag is the version and there is +nothing to keep in step with it. + +Closing a proposal issue without tagging skips that release; the next promotion +opens a new proposal. + ## What not to add - Root `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, or duplicate agent policy files. @@ -66,4 +101,3 @@ merge commits. Before starting significant work, [open an issue](https://github.com/z-shell/zi/issues/new/choose) to discuss the change. See also the [community contributing guidelines](https://github.com/z-shell/community/blob/main/docs/CONTRIBUTING_GUIDELINES.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). -````