audita/docs/release.md

# 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 builds the ReleaseKit
version selected by `go.mod` into ignored `bin/releasekit`. It uses temporary
copies of `go.mod` and `go.sum` for tool dependency preparation; 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 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 existing Go 1.25.5 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.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.