6.8 KiB
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, and POSIX shell. 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.