promptkit/docs/release.md

Release Procedure

This runbook implements the release policy. 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:

export GOTOOLCHAIN=local
go version

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

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. Prepare dependency caches before committing the candidate:

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:

[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. 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 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

./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 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 and CLI contract own shared checks and exit-status definitions.

Deliver The Hosted Release

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

./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:

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 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. Do not retry or remove the local tag until the authoritative outcome is resolved. ReleaseKit attempts to save private publication evidence and reports a record path or a separate recording warning. A recording failure does not change the publication outcome.

Use the recovery command reported for that attempt, or discover local records and explicitly select the matching attempt:

./scripts/releasekit.sh publication-attempts
./scripts/releasekit.sh reconcile --record /absolute/path/to/selected-record.json

Discovery is local; reconciliation observes the original destination without rerunning validation, changing tags, or delivering hosted content. Neither is a routine gate after successful publication. Follow the upstream recovery procedure for outcomes, incomplete evidence, and older attempts without records.

Records are stored under Git's common directory by default and can contain credential-bearing endpoints. Keep them private, out of source control and shared logs; retain them while needed for recovery and remove them when that value expires. See the evidence guide for storage and retention details.

Current absence does not prove a version was never published. Remove a retained local tag only after establishing absence and confirming it was not already published or used by another release channel. Never reuse a known published version or replace a published tag or hosted page. Corrections require a new appropriate version.