promptkit/docs/release.md

# Release Procedure

This runbook implements the [release policy](policy/release.md). Promptkit
publishes source-only Go module tags from `main` to `origin`, followed by a
page-only Gitea release. Successful publication of the intended tag, with its
source commit available on `main`, completes the source release. Report hosted
delivery separately. Do not wait for CI or Go module availability.

## Prepare The Candidate

Required tools are Git, Go with race-detector support, POSIX shell, and Python
3. Work from the repository root with push access to `origin`.

Use the latest Go installation available locally for the release tool and its
child commands. Put it first on `PATH` and keep it selected throughout:

```sh
export GOTOOLCHAIN=local
go version
```

For a minor release, normally advance the consumer minimum to the initial
stable patch of that Go series:

```sh
release_go_version=$(go env GOVERSION)
release_go_series=${release_go_version#go}
release_go_series=${release_go_series%.*}
go mod edit "-go=${release_go_series}.0"
```

Retain a higher patch minimum when required by a dependency or identified fix.
For a patch release, preserve the existing minimum. Explain minimum increases
under the [versioning policy](policy/release.md#versioning-and-compatibility).
Prepare dependency caches before committing the candidate:

```sh
go mod download
```

Choose an unused stable version and create `docs/releases/<version>.md` with a
title containing `Promptkit` and that exact version, a short summary, and any
compatibility impact or upgrade instructions. End the note with:

```markdown
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/vX.Y.Z/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/vX.Y.Z/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/vX.Y.Z/docs/oss/attribution.md)
```

Substitute the selected version and check the paths against the candidate;
future tag URLs need not resolve during preparation. Follow the
[OSS policy](policy/oss.md). Historical notes and tags remain unchanged.

Supply delivery credentials through `RELEASEKIT_GITEA_TOKEN` or the ignored
local file `.releasekit/gitea-token`, with owner-only file permissions. A
nonblank environment value takes precedence. Source publication neither reads
nor requires this token. The [profile](../releasekit.json) selects the token
path for committed-file protection; keep credentials out of commits and logs.

Retire completed roadmaps, preserve unfinished work, and repair affected links.
Review and commit the candidate on `main`, including any module updates, then
push `main` to `origin` before publishing its tag.

## Validate And Publish

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

The launcher uses `go tool` to build or reuse the module-selected ReleaseKit
executable in Go's cache, using the selected local toolchain. ReleaseKit runs
the [profile's checks](../releasekit.json) once, verifies publication state, and
publishes only the intended tag. Preserve its native exit status and diagnostic.
Successful publication needs no separate remote read-back or CI wait.

For optional local diagnosis, use `./scripts/releasekit.sh check VERSION`.
It is not a required step before publication. The upstream
[candidate-check guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.7.0/docs/consumers/check.md)
and [CLI contract](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.7.0/docs/cli.md)
own shared checks and exit-status definitions.

## Deliver The Hosted Release

After source publication, keep a clean checkout at the published tag's commit:

```sh
./scripts/releasekit.sh deliver vMAJOR.MINOR.PATCH
```

The profile selects page-only Gitea delivery for this repository. The hosted
body is the complete checked-in note, including its licensing footer. There are
no binary assets, checksum manifests, candidate revalidation, or CI waits.
ReleaseKit checks delivery credentials during delivery, not as a publication
gate. Report the hosted URL on success; delivery failure leaves the source
release complete.

For a later retry, use a clean checkout of the original tag with its recorded
module files and supply the token there. In a separate checkout, for example:

```sh
git switch --detach vMAJOR.MINOR.PATCH
./scripts/releasekit.sh deliver vMAJOR.MINOR.PATCH
```

Resolve uncertain hosted writes before retrying the same immutable version.
Matching content is accepted; conflicts are not overwritten. Do not rerun
`publish` or move tags to repair delivery. Follow the upstream
[delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.7.0/docs/consumers/delivery.md)
for result interpretation and recovery. These commands apply to tags containing
this delivery configuration; older releases retain their original workflows.

## Failure Recovery

For source-publication failures, use ReleaseKit's status and diagnostic to
distinguish a candidate defect from a publication conflict. Correct and commit
candidate defects, push `main`, and rerun publication as appropriate. A failure
after local tag creation may leave a ref even when its object ID is unavailable.

Status 3 means the push outcome remains unknown. Preserve the captured endpoint,
version, and tag object from that attempt; do not retry or remove the local tag
until the authoritative outcome is resolved. Diagnostics mask HTTP(S) credentials,
so use the actual captured endpoint rather than a redacted display. Follow the
upstream [failure-recovery procedure](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.7.0/docs/release.md#resolve-failures):

```sh
releasekit_endpoint='COPY_CAPTURED_ENDPOINT'
releasekit_version='vX.Y.Z'
test "$(git ls-remote --get-url -- "$releasekit_endpoint")" = "$releasekit_endpoint" &&
  git ls-remote --refs -- "$releasekit_endpoint" "refs/tags/$releasekit_version"
```

An exact tag-object match confirms publication. Absence is established only if
both checks succeed and the tag is missing; a failed check leaves the outcome
unknown. Remove an unpublished local tag only after confirming authoritative
absence. Never move or replace a published tag or hosted page. Corrections to
published source or content require a new appropriate version.