safe superbiche/safe
publishing.md

Publishing

Release Artifacts

safe releases are manual until the release process is proven. A release must be consumer-verifiable before it is published.

Release baseline:

  • signed annotated tag vX.Y.Z;
  • immutable GitHub Release;
  • safe-vX.Y.Z.tar.gz;
  • SHA256SUMS;
  • SHA256SUMS.asc.

Prepare release metadata on a release branch and commit it:

scripts/release check
git add VERSION CHANGELOG.md
git commit -m "Release vX.Y.Z"

Open a pull request, wait for review/checks, and merge it into main before creating any tag or release assets. This repository uses squash-only merges, so tagging the pre-merge release branch would produce a tag that is not in the published main history.

After the PR is merged, fetch and check out the merged default branch:

git fetch origin main
git switch main
git merge --ff-only origin/main

Create the signed tag on the merged main commit:

git tag -s vX.Y.Z -m "vX.Y.Z"

Create release assets from that signed tag:

scripts/release package

Sign the checksum file:

scripts/release sign-checksums

Verify local outputs:

scripts/release verify-checksums
scripts/release verify-signature

Upload these release assets:

dist/safe-vX.Y.Z.tar.gz
dist/SHA256SUMS
dist/SHA256SUMS.asc

Release notes must include checksum and signature verification commands:

sha256sum -c SHA256SUMS
gpg --verify SHA256SUMS.asc SHA256SUMS

CI provenance is not claimed for manual releases.

Do not create or publish a release for a version that has not landed in main. The tag, archive, and GitHub Release should all describe the merged main commit.

Documentation

The docs are built with MkDocs and published to GitHub Pages with Mike. Mike keeps multiple versions on the gh-pages branch and writes the versions.json metadata that the superbiche theme uses for its version selector.

Setup

Install the local docs toolchain from the repository root:

scripts/docs deps

This installs MkDocs, Mike, and the local superbiche theme package.

Local Builds

Build the current docs:

scripts/docs build

Serve the current docs:

scripts/docs serve

Serve the versioned gh-pages output locally:

scripts/docs mike-serve

Publish

Publish a new release version and move the latest alias:

scripts/docs deploy-latest 0.1

Publish an additional named version without changing latest:

scripts/docs deploy dev

Set the root redirect:

scripts/docs set-default latest

List deployed versions:

scripts/docs list

GitHub Pages

Configure GitHub Pages to serve from the gh-pages branch. The published site URL is:

https://superbiche.github.io/safe/

The root URL redirects to the version selected with scripts/docs set-default.