152 lines
7.1 KiB
Markdown
152 lines
7.1 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
|
|
invokes the module-selected ReleaseKit tool. A confirmed source tag completes
|
|
the release; Woodpecker reports binary delivery separately.
|
|
|
|
## Prerequisites
|
|
|
|
Use Bash and Git. 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.
|
|
|
|
The source-build minimum is Go 1.26.0, declared in [go.mod](../go.mod).
|
|
This minimum is required by the selected ReleaseKit dependency.
|
|
Distributed executables do not require a Go installation. The selected release
|
|
toolchain is Go 1.26.8, matching the current Woodpecker image and distributed
|
|
runtime notices. Use that local installation for tool bootstrap, candidate
|
|
validation, and release builds. Replace the installation path below with its
|
|
actual directory:
|
|
|
|
```sh
|
|
export PATH="/path/to/go1.26.8/bin:$PATH"
|
|
export GOTOOLCHAIN=local
|
|
go version
|
|
```
|
|
|
|
Record the reported toolchain with the validation results. The
|
|
[release policy](policy/release.md#consumer-minimum-and-release-toolchain)
|
|
governs the distinction between the consumer minimum and release toolchain,
|
|
support across a Go series, and versioning of minimum increases. When selecting
|
|
a different release toolchain, update the CI image and applicable runtime
|
|
attribution together; a newer build patch alone need not raise the minimum.
|
|
|
|
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. ReleaseKit's CLI is registered as a Go tool dependency;
|
|
`go mod tidy` retains its dependencies and checksums. The release wrapper changes
|
|
to the repository root and invokes `go tool releasekit` with workspace discovery
|
|
and automatic toolchain downloads disabled. Go builds or reuses the selected
|
|
tool from its normal build cache. Tool preparation precedes offline 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 ReleaseKit's `ci-deliver` command for tags under
|
|
`refs/tags/v*`. The tagged `go.mod` selects the ReleaseKit version, and
|
|
`releasekit.json` supplies Audita's build and delivery settings:
|
|
|
|
- `audita-<version>-linux-amd64`
|
|
- `audita-<version>-linux-arm64`
|
|
- `SHA256SUMS`
|
|
|
|
Before running Go, the workflow fetches and verifies the event tag, checks it
|
|
out detached, and confirms the source tree is clean. It copies the tagged
|
|
`go.mod` and `go.sum` into temporary module metadata outside the checkout. Go
|
|
confirms that this configuration selects ReleaseKit, then builds its CLI using
|
|
an alternate `-modfile`. The bootstrap executable and temporary files remain
|
|
outside the tagged source. The workflow runs with the selected Go 1.26.8 image,
|
|
`GOWORK=off`, and `GOTOOLCHAIN=local`.
|
|
|
|
The resulting executable receives:
|
|
|
|
```sh
|
|
"$${bootstrap_dir}/releasekit" ci-deliver \
|
|
--repo "$${CI_WORKSPACE}" \
|
|
--commit "$${CI_COMMIT_SHA}" \
|
|
"$${CI_COMMIT_TAG}"
|
|
```
|
|
|
|
The workflow maps the existing `GITEA_RELEASE_TOKEN` secret to
|
|
`RELEASEKIT_GITEA_TOKEN`. The complete checked-in release note, including its
|
|
licensing footer, supplies the hosted release body. 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.3.0/docs/consumers/publish.md)
|
|
and [delivery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.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.3.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.3.0/docs/consumers/delivery.md).
|
|
A source or published-content correction requires a new appropriate version;
|
|
leave the original tag and its contents intact.
|