85 lines
3.9 KiB
Markdown
85 lines
3.9 KiB
Markdown
# Source Releases
|
|
|
|
This is the executable runbook for [Release Policy](policy/release.md).
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
./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](policy/release.md#notarius-gate-selection) 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:
|
|
|
|
```sh
|
|
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.
|