147 lines
6.9 KiB
Markdown
147 lines
6.9 KiB
Markdown
# Release Policy
|
|
|
|
**Base Policy Version:** 1.0
|
|
|
|
**Last Updated:** 2026-09-23
|
|
|
|
## Purpose And Adoption Scope
|
|
|
|
This policy owns Promptkit's release requirements and compatibility rules.
|
|
The [release procedure](../release.md) 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](../formats.md#built-in-profile-catalog)
|
|
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:
|
|
|
|
```markdown
|
|
# 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
|
|
|
|
The [publication script](../../scripts/release.sh) runs the
|
|
[local checks](../../scripts/release-check.sh) 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.
|