121 lines
5.5 KiB
Markdown
121 lines
5.5 KiB
Markdown
# Releasing Audita
|
|
|
|
The [release policy](policy/release.md) owns release requirements. This runbook
|
|
uses the native commands in [scripts/release.sh](../scripts/release.sh), which
|
|
builds and invokes ReleaseKit. A confirmed source tag completes the release;
|
|
Woodpecker reports binary delivery separately.
|
|
|
|
## Prerequisites
|
|
|
|
Use Bash, Git, and Go 1.25.5 or newer. The authoritative remote is `origin`,
|
|
which must point to `https://gitea.maximumdirect.net/eric/audita.git`; the
|
|
primary branch is `main`. Source publication needs no delivery credential.
|
|
Woodpecker uses the existing `GITEA_RELEASE_TOKEN` secret for delivery.
|
|
|
|
Prepare dependencies before offline candidate validation:
|
|
|
|
```sh
|
|
GOWORK=off GOTOOLCHAIN=local go mod download
|
|
```
|
|
|
|
If dependency preparation changes `go.mod` or `go.sum`, include those changes in
|
|
the committed candidate. The release wrapper separately bootstraps the pinned
|
|
ReleaseKit command into ignored `bin/releasekit`; that build is tool preparation,
|
|
not candidate validation.
|
|
|
|
## Prepare and publish the candidate
|
|
|
|
Choose an unused version under the [release policy](policy/release.md), write
|
|
`docs/releases/<version>.md`, and begin it with `# Audita <version>`. Include a
|
|
short summary, relevant compatibility or upgrade instructions, and the required
|
|
`COPYRIGHT | LICENSE | ATTRIBUTION` footer with links for the selected version.
|
|
Update affected canonical documentation with behavior changes.
|
|
|
|
End each note with this footer, substituting its complete tag for `<version>`:
|
|
|
|
```markdown
|
|
[COPYRIGHT](https://gitea.maximumdirect.net/eric/audita/src/tag/<version>/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/audita/src/tag/<version>/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/audita/src/tag/<version>/docs/oss/attribution.md)
|
|
```
|
|
|
|
Commit the complete candidate on `main`, including the release note, then push
|
|
the branch first:
|
|
|
|
```sh
|
|
git push origin main
|
|
```
|
|
|
|
Record the candidate commit. Before publication, remote `main` must identify
|
|
that exact commit. ReleaseKit checks this along with the clean candidate, note,
|
|
version, and remote tag state.
|
|
|
|
Publish from the repository root, substituting the selected version:
|
|
|
|
```sh
|
|
bash scripts/release.sh publish VERSION
|
|
```
|
|
|
|
The command runs `go test -mod=readonly -count=1 ./...` once with module and
|
|
toolchain network access disabled, builds the profile's Linux amd64 and arm64
|
|
targets, and checks the native version output. It creates an annotated tag whose
|
|
message comes from the committed note, then pushes the exact tag object. A
|
|
successful publication completes the source release without waiting for CI or
|
|
checking artifact availability.
|
|
|
|
`bash scripts/release.sh check VERSION` is an optional local diagnostic. It
|
|
does not inspect remote availability or publish a tag, and it is not a required
|
|
step before `publish`, which performs its own candidate validation.
|
|
|
|
The wrapper preserves ReleaseKit's exit status: `0` means confirmed publication;
|
|
`1` means a known validation or publication failure/conflict; `2` means usage,
|
|
profile, or version input error; and `3` means the push outcome remains unknown.
|
|
|
|
## Binary delivery
|
|
|
|
Woodpecker runs the pinned ReleaseKit `ci-deliver` command for tags under
|
|
`refs/tags/v*`. It verifies the triggering commit against the tag, prepares the
|
|
tagged source, and uses `releasekit.json` to build and deliver:
|
|
|
|
- `audita-<version>-linux-amd64`
|
|
- `audita-<version>-linux-arm64`
|
|
- `SHA256SUMS`
|
|
|
|
The workflow invokes:
|
|
|
|
```sh
|
|
go run gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@${RELEASEKIT_VERSION} ci-deliver \
|
|
--repo "$${CI_WORKSPACE}" \
|
|
--commit "$${CI_COMMIT_SHA}" \
|
|
"$${CI_COMMIT_TAG}"
|
|
```
|
|
|
|
Woodpecker sets `RELEASEKIT_VERSION` to `v0.1.0` for this workflow.
|
|
|
|
The complete checked-in release note, including its licensing footer, supplies
|
|
the hosted release body. The workflow maps the existing `GITEA_RELEASE_TOKEN`
|
|
secret to `RELEASEKIT_GITEA_TOKEN`. Delivery runs independently after source
|
|
publication; its status and logs report delivery progress or failure.
|
|
|
|
ReleaseKit handles content-aware retries and retained-artifact recovery. See
|
|
the pinned [publication recovery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/consumers/publish.md)
|
|
and [delivery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/consumers/delivery.md)
|
|
for those mechanics. A delivery failure does not undo a confirmed source
|
|
release. Retry the same immutable tag after resolving the reported state; do not
|
|
replace published files or a checksum manifest.
|
|
|
|
## Failure and recovery
|
|
|
|
Fix validation failures in a new committed candidate, then rerun `publish`.
|
|
After a failed push, ReleaseKit retains the local annotated tag and reports the
|
|
captured authoritative endpoint and publication state. Resolve the result
|
|
against that endpoint before retrying. An exact remote tag-object match, with
|
|
its source available on remote `main`, can confirm publication. If the remote
|
|
state cannot be read, the result remains unknown; do not remove or replace the
|
|
tag while uncertain. Follow the pinned [publication recovery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/consumers/publish.md)
|
|
for object-level recovery details.
|
|
|
|
A source-release success and artifact-delivery status are separate. For a
|
|
partial or uncertain delivery, inspect the job output and follow the pinned
|
|
[delivery recovery guidance](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/consumers/delivery.md).
|
|
A source or published-content correction requires a new appropriate version;
|
|
leave the original tag and its contents intact.
|