3.7 KiB
Release Procedure
This runbook implements the release policy. A successful push of the selected annotated tag to origin completes the release. Never wait for CI to finish or succeed.
Prepare The Candidate
Required tools are Git, Go with race-detector support, POSIX shell, and Python 3. Publication requires push access to origin. Work from the repository root.
Select an unused version and create docs/releases/<version>.md using the
required structure. Describe
compatibility impact and consumer actions and update affected canonical docs.
For catalog updates, record selected catalog versions and any consumer action,
linking to the catalog policy rather than repeating its contracts.
Retire completed roadmaps, preserving planned or deferred work and repairing links. This is housekeeping, not a separate approval gate. Review changes through the ordinary development workflow, commit them, and push main to origin. No repeated release-specific diff review is required.
Validate And Publish
Run the following with the chosen unused version (replace the placeholder):
./scripts/release.sh vMAJOR.MINOR.PATCH
The publication script checks a clean, synchronized main candidate, the version and unused tag, and the release note's title and required headings. It runs the local checks once, rechecks candidate identity and publication state, generates the annotation from the committed note plus the validated commit, and pushes only the selected annotated tag.
There is no separate tag-message authoring, example-output inspection, metadata inspection, or human sign-off. Compatibility and release-note content remain ordinary editorial responsibilities. Development validation is useful but does not require a second full run before invoking the publication script.
The script stops successfully after the tag push. CI completion, CI success, remote read-back, and Go module availability are not release completion gates. Do not wait or poll for them. Provider probes and inference calls are never part of release validation.
Catalog Profile Compatibility
The release policy owns the catalog compatibility boundary. This heading preserves older incoming links.
Failure Recovery
If local checks fail, fix the candidate, commit and push changes, then rerun the publication command. It never automatically removes a tag.
If a push fails or its result is ambiguous, set RELEASE_VERSION to the
attempted version and inspect origin before retrying:
git ls-remote --tags origin "refs/tags/$RELEASE_VERSION" "refs/tags/$RELEASE_VERSION^{}"
git rev-parse "refs/tags/$RELEASE_VERSION" "refs/tags/$RELEASE_VERSION^{}"
Matching remote tag and peeled commit values confirm publication, even if the push command reported an error. If the remote query fails, publication status is still unknown. Do not delete or recreate the local tag until absence on origin is confirmed. Once confirmed unpublished, an unsuccessful attempt's local tag can be removed and the publication command rerun. Never overwrite a published tag.
CI or module-resolution problems may be investigated separately; temporary service, network, or authentication failures do not require another release. Only an actual defect requiring changes to published contents warrants a new appropriate version. See the recovery policy.
Policy Changes
Update the policy and this procedure together when changing release governance. Consumers own their dependency-availability and release checks; their readiness does not delay completion of a Promptkit release.