promptkit/docs/policy/release.md

Release Policy

Base Policy Version: 1.2

Last Updated: 2026-09-26

Purpose And Adoption Scope

This policy owns Promptkit's release requirements and compatibility rules. The release procedure owns the commands used to satisfy them. This scoped adoption applies to releases prepared after its adoption on 2026-09-23. Published tags and historical notes are not rewritten to retrofit the new note format.

Release Model And Compatibility

Promptkit publishes source-only Go module releases from committed, pushed main candidates through annotated vMAJOR.MINOR.PATCH tags. It publishes no binaries, hosted releases, or other artifacts and uses maintainer-run validation rather than hosted CI. Versions must be unused locally and on origin; the existing procedure accepts stable version tags only.

Before v1, minor releases may change the public API and patches preserve compatibility within their minor line, subject to the catalog-data provision below. Release notes must identify compatibility impact, public API changes, and required consumer action. The source tag identifies the exact release; the checked-in note at that tag records its historical summary.

Catalog Profile Compatibility

External catalog profile data may be added, removed, renamed, or modified without deprecation or advance notice. This exception is limited to profile data imported from the maintained catalog modules. It does not weaken ordinary compatibility for Promptkit's public Go API, configuration and format semantics, runtime behavior, catalog-module APIs, manifest schema, backend definitions, or consumer-owned definitions.

Within the catalog versions selected and tested by a Promptkit release, and unless a consumer overrides the name or its base, Promptkit keeps the literal profile IDs promptkit-openrouter-standard and promptkit-openrouter-auto available. The names do not promise a permanent model, backend, routing behavior, settings, cost, output, or upstream availability. The framework format reference owns their current definitions.

v0.10.0 is the initial minor release for this compatibility transition. Afterward, catalog-only updates and adjustments to the current selections may ship in a patch release when all other compatibility obligations remain intact. External profile removals can require consumer action; they are not automatic migrations.

Catalog adoption and release validation remain local and offline. They do not probe provider endpoints, request model lists, or make inference calls.

Release Documentation

Every new release must include docs/releases/<version>.md in the tagged source, using the complete tag as the filename. Its title contains Promptkit and that exact version. Use this structure:

# Promptkit vMAJOR.MINOR.PATCH

This release ...

## Summary

## Compatibility

## Upgrade

## Changes

State “No action required” or “None” where appropriate rather than omitting a section. Keep exact current contracts in their canonical documents and link to them. Update affected canonical documentation in the same candidate.

These notes are historical records, not optional disposable guidance. Published release-note contents must not be replaced under the same version. Corrections belong in a subsequent release. Annotated-tag messages complement the checked-in note: generate the annotation from that note and the validated commit rather than maintaining a second summary.

Validation And Publication

New release notes prepared after the 2026-09-26 OSS-policy adoption end with the licensing footer. The release procedure owns absolute, release-pinned URLs. This is prospective preparation work, not a new approval or network-validation gate; historical notes and tags are not reformatted.

The publication script runs the local checks once for the final candidate. Retain clean-candidate, synchronized-main, unused-version, module-hygiene, release-note structure, and tag-target checks. Publish only the selected tag ref. Changing the candidate requires fresh validation. No provider endpoint probes or inference calls are release checks.

Release-note content and retirement of completed roadmaps are preparation responsibilities, not separate human sign-off gates. Preserve planned and deferred work and repair links. Ordinary change review covers unintended files, secrets, and private data; do not repeat it as a release-specific approval.

A successful tag push to origin completes the release. Never wait for CI to finish or succeed. CI results, remote read-back, and Go module availability are informational follow-ups, not completion gates. An ambiguous push result requires confirming publication on origin, not waiting for CI.

Immutability And Failure Recovery

Never move, replace, recreate, or delete a published tag or replace published release contents. If validation fails before publication, correct the candidate, rerun the complete checks, and repeat the publication guards. Remove an unpublished local tag only after confirming it was not published.

If publication or subsequent investigation reveals a defect, leave the published release intact. Correct the defect on main, select a new patch or other semantically appropriate version, write its matching release note, and repeat the complete procedure. If publication status is uncertain, inspect the authoritative remote before deciding whether a tag is unpublished; do not overwrite it to retry.

Transient network, authentication, CI, or module-availability failures do not by themselves warrant a new version. Investigate separately and publish a corrective release only when published contents actually need changing.

Policy Exceptions And Deliberate Scope

This adoption follows the maintainer-approved lean workflow rather than every base-policy guard:

• Collision checks concern origin, the authoritative publication destination, rather than every configured remote. Local and origin tag checks, synchronized main, and an explicit selected-ref push protect the actual release channel.
• Automated local validation and publication-state checks replace manual mechanical inspections and separate human sign-offs. Ordinary change review, editorial responsibility for release notes, and roadmap housekeeping remain; repeating them as approvals would add friction without distinct protection.
• Successful tag publication completes this source-only release. CI can be slow or unreliable, and module availability depends on external services. Neither is a completion gate. Local candidate validation and explicit tag-target checks protect publication; ambiguous push results are resolved against origin. Actual defects are corrected in a new release, never by replacing a tag.

Ignored local files are not prohibited merely because they exist: they are not included in the tagged commit. The clean-candidate guard and ordinary review of tracked changes protect the published contents.

The catalog profile provision preserves an already approved compatibility boundary; it does not extend volatility to backend definitions or runtime contracts. Further release-governance changes require deliberate approval.