promptkit/docs/release.md

Release Procedure

Release Model

Promptkit publishes a Go library through source commits and semantic Go module tags. It does not publish runnable binaries or binary packages and does not currently use hosted CI. The release maintainer performs and records the required validation.

The first planned release is v0.1.0. Do not create that tag until the framework has been extracted and the resulting public library has passed this procedure. Later tags use the vMAJOR.MINOR.PATCH form. While Promptkit remains pre-v1, release notes must identify intentional public API changes and any consumer migration required by them.

Prepare The Release

Work from a clean checkout of the intended release commit, outside any Go workspace and without a local module replacement. Confirm the source commit is already published through the normal branch workflow.

From the Promptkit repository root, verify the checkout:

gowork=$(go env GOWORK)
test -z "$gowork" || test "$gowork" = off
test -z "$(git status --short)"
git fetch --tags origin

Confirm the module and root package metadata:

go list -m -f '{{.Path}} {{.GoVersion}}'
go list -f '{{.Name}} {{.ImportPath}}' .

The output must be:

gitea.maximumdirect.net/eric/promptkit 1.25.5
promptkit gitea.maximumdirect.net/eric/promptkit

Run the same default Go validation required by the development guide:

go test ./...
go vet ./...
go build ./...

Check every tracked Go file and repository whitespace:

gofmt -l $(git ls-files '*.go')
git diff --check

The formatting command must produce no paths. Follow every maintained Markdown link and confirm its target exists. Review the repository for generated binaries, test or coverage output, credentials, template residue, and other files that do not belong in source control.

Confirm that no workspace override is tracked and that go.mod contains no replace directive:

git ls-files go.work go.work.sum
rg -n '^replace\b' go.mod

Both commands must produce no output. Re-run git status --short and require a clean result after every validation and review check.

Create And Publish The Tag

Choose the semantic version from the intended compatibility change. Record the release commit before tagging:

release_version=v0.1.0
release_commit=$(git rev-parse HEAD)

Replace the example version for later releases and keep both values in the same shell for the remaining commands. Confirm the tag does not already exist locally or remotely:

test -z "$(git tag --list "$release_version")"
test -z "$(git ls-remote --tags origin "refs/tags/$release_version")"

Create an annotated tag whose message identifies the release and records that the documented validation passed for the tagged commit:

git tag --annotate "$release_version" \
  --message "Promptkit $release_version; documented validation passed for $release_commit"

Inspect the tag before publication:

git show --no-patch --decorate "$release_version"
test "$(git rev-list -n 1 "$release_version")" = "$release_commit"

Publish the tag without relying on a hosting-provider-specific release interface:

git push origin "refs/tags/$release_version"

Verify Publication

Confirm that the remote tag object matches the local annotated tag and still resolves to the intended source commit:

remote_tag=$(git ls-remote --tags origin "refs/tags/$release_version" | awk '{print $1}')
test "$remote_tag" = "$(git rev-parse "refs/tags/$release_version")"
test "$(git rev-list -n 1 "refs/tags/$release_version")" = "$release_commit"

Promptkit must publish the required tag before Scriptorium or another consumer publishes a release that depends on that version. Released consumer modules must not use a local replacement or unpublished Promptkit revision.

Policy Changes

Document and approve a durable policy change before introducing hosted automation, binary artifacts, or different release governance. Update this procedure in the same change so maintainers do not rely on hidden release requirements.