notarius/docs/release.md

Source Releases

This is the executable runbook for Release Policy. Notarius publishes an immutable lightweight tag and its checked-in release note, not binaries or Gitea release objects. Linux is supported; macOS is best-effort for development, and Windows is unsupported. main on origin is authoritative.

Prepare

Use Git, a POSIX shell, and Go 1.25.5 or newer. Configure ordinary Git credentials for origin and private-module access without putting secrets in the repository. Prepare dependencies before offline validation where necessary:

GOWORK=off GOPRIVATE=gitea.maximumdirect.net go mod download

Choose an unused stable version under the policy's compatibility rules. Add docs/releases/<version>.md, starting with # Notarius <version>, with a concise summary and relevant compatibility/upgrade information. No fixed section list is required. Update current documentation with behavior changes; retire only completed roadmaps and preserve planned/deferred work. Commit the candidate on main after ordinary change review. There is no separate release sign-off.

Publish

Run one command from the repository with the actual selected version:

./scripts/release.sh vMAJOR.MINOR.PATCH

The command checks version availability on origin, branch and worktree state, and the matching note. It runs the complete offline default test suite once and a native CLI build/version check with GOWORK=off. The gate rationale explains the selected checks. It then rechecks candidate and publication state, pushes the exact candidate to main without force, creates a lightweight tag, and pushes only that tag. It neither rewrites history nor publishes other local tags.

A successful tag push completes the source release. The command does not wait for CI or verify consumer installation/module availability. Tag CI is advisory validation only; there are no asynchronous deliverables to await.

Failure And Recovery

Before publication, correct failed checks, commit any changes, and rerun the command. If the candidate changes during validation, validation must run again on the new candidate. A failed branch push publishes no tag.

On a failed or ambiguous push, the command queries the affected remote ref. If a tag push reports failure but the intended lightweight tag is confirmed on the remote, publication succeeded. Otherwise it stops and reports failure or unknown status, leaving any local tag intact for inspection. Do not blindly rerun, force push, or delete a possibly published tag.

Inspect authoritative state before retrying:

git ls-remote origin refs/heads/main refs/tags/vMAJOR.MINOR.PATCH
git rev-parse vMAJOR.MINOR.PATCH

If the intended tag exists remotely, leave it immutable. If it is absent and you have confirmed that the local tag was never published or used by a release channel, remove only that unpublished local tag, then rerun the command. A failed remote query is not proof of absence. Network/authentication failures alone do not require a new version. A defect requiring changes to published source requires a new semantically appropriate version and matching note.

Optional Diagnostics

./scripts/check-release-source.sh <version> runs validation without publication. It is useful for diagnosis, but is not a required preliminary step that must repeat the publication command's checks.

Race tests, vet, module hygiene, formatting, example checks, and cross-builds may be run when relevant to a change; they are not additional release gates. The development guide and testing policy govern change-specific verification.

A fresh source install or exact-tag checkout/build may be used to investigate consumer availability after release. Such checks are optional and do not delay or reverse release completion. notarius --version is diagnostic; subprocess compatibility is defined by the receipt and artifact contracts.