Skip to content

docs(contributing): document release authorization and repair the fences #508

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

Merged
ss-o merged 1 commit into from
Sep 3, 2026
Merged

docs(contributing): document release authorization and repair the fences #508

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
42 changes: 38 additions & 4 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ Thank you for contributing! Please follow the guidelines below to keep the proje

## Branch model

````text
```text
main production and consumable ref
|-- hotfix-<id> urgent fixes that may target main
^
next integration branch; ordinary PRs target here
^
|-- feature-<id> new features
`-- bug-<id> bug fixes
```text
```

1. Branch ordinary work from `next`: `git switch -c bug-123 next`.
2. Target `next` from `feature-<id>` and `bug-<id>` branches.
Expand All @@ -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`

Expand All @@ -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 <notes-file>
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.
Expand All @@ -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).
````
Loading