eric/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Align policies with the standard and record their provenance

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-27 21:18:11 +00:00
parent 843d07b636
commit a16c2a38d6
13 changed files with 782 additions and 695 deletions
Download Patch File Download Diff File Expand all files Collapse all files

335
docs/policy/release.md
View File

@@ -1,30 +1,229 @@
# Release Policy
**Base Policy Version:** 1.2
**Base Policy Version:** 1.4
**Last Updated:** 2026-09-26
**Last Updated**: 2026-09-27
## Purpose And Adoption Scope
**Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
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.
## Purpose
## Release Model And Compatibility
This policy defines a proportionate workflow for validating and publishing an
intended source revision under a fresh version. Releases should require little
routine intervention, avoid repeated work, and preserve published contents.
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.
The repository-specific commands belong in `docs/release.md`. Historical release
summaries belong in `docs/releases/`. The procedure must agree with the adopted
policy and link to it rather than introduce additional release requirements.
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.
## Release Model And Completion
A source release identifies one exact committed source revision through an
immutable version tag and a version-matched, checked-in release note. The
primary release branch is `main` unless the adopted policy specifies otherwise.
The procedure must name the authoritative publication remote.
A successful push of the intended tag, with its source commit available on the
authoritative primary branch, completes the release. The source commit may be
pushed before the tag or published together with it through an atomic push.
The procedure must choose and document the supported approach.
Release commands must finish at successful publication. They must not wait for
or poll CI, require successful CI status, inspect downloadable artifacts, or
check consumer installation or Go module availability as completion gates.
A failed or ambiguous push requires resolving the authoritative remote state
before declaring success or retrying; successful pushes do not require a
separate remote read-back gate.
Repositories may publish source only. Additional binaries, images, packages,
checksums, or other declared deliverables may be published asynchronously from
the tagged source. The procedure must identify those deliverables and the
responsibility of their automation. Published deliverables must be traceable
to that source and identify the same version.
Track source-release completion and artifact delivery separately. Report delivery
failures and optional investigations under artifact-delivery status.
## Versioning And Compatibility
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
no leading zeroes. Prereleases require an explicit adopted policy defining
their format and use.
The selected version must be unused locally and on the authoritative remote.
Do not require queries to every configured remote or publication service.
A version known to have already been published must not be reused, even if the
normal guards do not inspect that channel. Adding a distribution channel
requires a deliberate update to the policy and procedure where needed.
For releases at or after `v1.0.0`:
- a major release may make intentional incompatible changes;
- a minor release may add backward-compatible behavior; and
- a patch release may make backward-compatible fixes.
Before `v1.0.0`, a minor release may change a documented public, operational,
configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must
not intentionally break those contracts within its minor line.
Additional compatibility promises and deliberate exceptions belong in the
adopted policy or canonical contract documentation. Release notes explain
changes; they do not redefine current compatibility contracts.
## Release Documentation
Every new release must include `docs/releases/<version>.md` in the tagged
source tree. Use the complete version tag as the filename and begin with a
title containing the product name and that exact version.
Include a short summary and any relevant compatibility impact or upgrade
instructions. Use the Promptkit section structure below and keep the note
proportionate to the change.
Keep exact current contracts in their canonical documents and update affected
documentation with the behavior change. Link to those documents from the note
where useful. If annotated tags are used, derive their summary from the
checked-in note.
Include the release footer defined by the [OSS policy](oss.md#discoverability)
in each new release document and preserve it on the hosted download page. The
release procedure defines the concrete URLs and publication mechanics. Prepare
these links with the release note; they do not add a network check or approval
gate.
Handle version selection, release-note content, and retirement of completed
roadmaps during preparation. Preserve planned and deferred work and repair
affected links when retiring roadmaps. Reuse ordinary change review for
unintended files, credentials, and private data. Scope release-content review
to the tagged source.
## Candidate Validation
Provide one publication command that validates the final committed candidate,
checks publication state, and publishes the intended refs. A validation-only
mode or command may be provided for diagnosis, but must not be a required step
before publication repeats the same checks.
Run the complete deterministic, offline default test suite once for the final
candidate, following the [testing policy](testing.md). For repositories that
publish builds, verify the required build targets. Select those targets for
the application's actual support commitments; native testing on each platform
and access to particular hardware are not default release prerequisites.
Additional gates must address a concrete risk that the existing checks do not
adequately cover. Do not automatically require linting, race testing, module
hygiene audits, documentation audits, credential scans, example validation, or
expanded platform matrices solely because they are possible. Retain such
checks when their distinct protection justifies their cost. A one-time migration
check must not silently become a permanent release requirement.
Release tests must not require real credentials, mutable application services,
paid APIs, provider probes, or inference calls. The procedure may describe dependency
preparation separately from offline validation.
Avoid duplicate validation across release phases. Successful checks for the
same final candidate need not be repeated solely to satisfy another phase;
any reuse must clearly apply to that exact candidate. Persistent validation
caches are not required. If the candidate changes, validate the new candidate.
Cheap publication-state checks may be repeated immediately before pushing
because local or remote state may have changed during validation.
Automate mechanical guards. Human review gates are strongly disfavored: add one
only through an explicit project-specific policy decision explaining the
concrete risk and why ordinary change review or automation is insufficient.
Do not add routine confirmations for checks the command can perform itself.
## Publication Guards
Automate the checks needed to publish the intended source under a fresh version:
- the version has the adopted format and is unused locally and on the
authoritative remote;
- the worktree and index are clean on the primary release branch;
- the source being published is the exact candidate that passed validation,
including its matching release note;
- the remote primary branch already identifies that candidate, or an atomic
source/tag push will advance it to that candidate without discarding remote
history; and
- the tag identifies the validated candidate and only the intended refs are
published.
Fetch the authoritative branch and tag state as needed for these checks.
Do not force branch or tag updates to bypass a failed guard. Publish explicit
refs rather than all local tags. Do not require CI success, publication-service
availability checks, or a separate manual confirmation for each guard.
## Immutability And Failure Recovery
Published version tags and published contents are immutable. Do not move,
overwrite, recreate, or delete a published tag, or replace a published artifact,
checksum, signature, provenance statement, or release note under that version.
The checked-in note at the immutable tag is that release's historical record.
If validation fails before publication, correct and commit the candidate and
rerun the publication command. If a push fails or its outcome is ambiguous,
inspect the authoritative remote before retrying. Remove an unpublished local
tag only after confirming it was never published or used by a release channel.
An unavailable remote leaves publication status unknown; do not overwrite a tag
to resolve uncertainty.
Transient network, authentication, CI, or consumer-availability failures do not
by themselves require a new version. Asynchronous delivery may be retried from
the same immutable tag. Missing artifacts may be published later, provided
existing published contents are not replaced and the additions remain consistent
with the tagged source and any already-published checksum manifest. If that
cannot be achieved, publish a new version.
A defect requiring changes to published source or contents requires a corrected
commit, a new semantically appropriate version, a matching release note, and
the release procedure again. Leave the original release intact. A channel's
yank, deprecation, or advisory mechanism may warn consumers away from a defective
release without replacing its contents or reusing its version.
## Repository Release Procedure
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
identify:
1. prerequisites, primary branch, and authoritative remote;
2. version and release-note preparation;
3. one publication command with its selected local checks and automated guards;
4. declared deliverables, required build targets, and automation responsibilities;
5. the successful-push completion point and separately reported delivery status;
and
6. failure handling, ambiguous-push recovery, and asynchronous delivery retries.
Use copyable commands where practical. Keep optional diagnostics and consumer
verification clearly optional. The procedure must not turn preparation work,
ordinary change review, or post-publication investigation into additional
release gates.
## Promptkit Release Configuration
The release-note requirements were adopted on 2026-09-23 and licensing
navigation on 2026-09-26. Apply them prospectively; previously published notes
and tags retain their original records.
Promptkit publishes source-only Go modules from main to origin on Gitea, using
annotated stable SemVer tags. It has no binaries, hosted download pages, or
asynchronous deliverables. The source commit is pushed through main before the
tag. The [release procedure](../release.md) owns commands and recovery.
The existing publication script requires Summary, Compatibility, Upgrade, and
Changes headings beneath a title of `# Promptkit vMAJOR.MINOR.PATCH`. State
“No action required” or “None” where appropriate. This retained local structure
matches the automated release-note guard; changing it is separate work.
The [publication script](../../scripts/release.sh) runs the
[local checks](../../scripts/release-check.sh) once for the final committed
candidate: race-enabled tests, vet, three offline consumer examples, tracked
Go formatting, Markdown links, module/workspace hygiene, whitespace, and a
credential-pattern scan. These protect concurrency, assembled library use,
source distribution, and documentation integrity. A separate ordinary test run
or standalone build is not an additional release gate. Candidate, tag, and
synchronized-main checks remain automated. No CI or module-availability wait
is required. Licensing footer URLs are preparation work, not a network gate.
## Catalog Profile Compatibility
@@ -51,101 +250,3 @@ 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
New release notes prepared after the 2026-09-26 OSS-policy adoption end with
the [licensing footer](oss.md#discoverability). 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](../../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.