98 lines
4.7 KiB
Markdown
98 lines
4.7 KiB
Markdown
# Release Procedure
|
|
|
|
This runbook implements the [release policy](policy/release.md). 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](policy/release.md#release-documentation). 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.
|
|
|
|
Follow the [OSS policy](policy/oss.md) when preparing licensing and attribution
|
|
changes. Each new note must end with the following navigation, replacing
|
|
`vMAJOR.MINOR.PATCH` with the selected release tag:
|
|
|
|
```markdown
|
|
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit/src/tag/vMAJOR.MINOR.PATCH/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/tag/vMAJOR.MINOR.PATCH/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/promptkit/src/tag/vMAJOR.MINOR.PATCH/docs/oss/attribution.md)
|
|
```
|
|
|
|
Check these file paths against the candidate; a future tag need not resolve
|
|
remotely during preparation. The annotated tag derives from this same note,
|
|
including its footer. Promptkit publishes no separate hosted release body or
|
|
download page. If such a channel is deliberately introduced, reuse the note
|
|
and preserve its footer. No extra network checks, artifacts, or approval gates
|
|
are introduced, and published notes are not retrofitted.
|
|
|
|
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):
|
|
|
|
```sh
|
|
./scripts/release.sh vMAJOR.MINOR.PATCH
|
|
```
|
|
|
|
The [publication script](../scripts/release.sh) 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](../scripts/release-check.sh)
|
|
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](policy/release.md#catalog-profile-compatibility) 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:
|
|
|
|
```sh
|
|
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/release.md#immutability-and-failure-recovery).
|
|
|
|
## 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.
|