Release Process

Cut a release with basicly release, which does every step up to the annotated tag. You choose the version, write the summary and push.

Rules

• Confirm that this repository releases with basicly release first. The skill ships to every repository that installs basicly, also to one with its own release process.
• Never do by hand a step that basicly release does. The command checks every precondition before the first write and restores the tree when a later step fails.
• Write the notes before the cut. The release commit and the tag are one step, so a later commit never reaches the tagged notes.
• Never clear a refusal by a manual run of the named tool. That records a witness for a check that the gate did not see pass.
• Never delete a changelog fragment to clear a refusal. A release note must not disappear without notice.
• The command never pushes. Push only when the user release request includes publication.
• The user release request authorizes the requested cut and publication. No grant is needed. Required release gates must still pass.

1. Check that the repository uses it

ls changelog.d/ 2>/dev/null; grep -n "## \[Unreleased\]" CHANGELOG.md

If either is missing, stop and follow the repository's own release document.

2. Write the notes

Each change has changelog.d/RECORD-ID.CATEGORY.md. Write a one-paragraph summary under ## [Unreleased], above its first ### heading. The fragment rules are in procedure.

3. Wait for green CI

Cut only from a commit whose CI run on the release branch passed. A red or running build is a stop.

4. Choose the version and run the dry run

uv run basicly release VERSION --issue RECORD-ID --dry-run

You choose major, minor or patch. The dry run writes nothing and lists every refusal at once; refusals gives each fix.

5. Cut the release

uv run basicly release VERSION --issue RECORD-ID

It bumps the version, regenerates projections, rewrites install pins, assembles the changelog, commits and tags. What else it does and the flags are in procedure.

6. Push and confirm

git push origin main
git push origin vX.Y.Z

Confirm that the tag workflow run is green and that the release page matches the summary. When the auto-mode classifier blocks a tag push, read auto-mode.