Skip to content

releasing.md

Latest commit

 

History

History
81 lines (52 loc) · 3.24 KB

releasing.md

File metadata and controls

81 lines (52 loc) · 3.24 KB
Raw

Releasing qi

This guide is for maintainers publishing a tagged qi version. User-facing compatibility policy remains in the README; automation is defined by the release workflow.

What the workflow does

A push of any tag matching v* starts the release workflow. It:

  1. requires a complete Semantic Versioning tag such as v0.1.0 or v0.2.0-beta.1;
  2. classifies a tag with a prerelease suffix as a GitHub prerelease;
  3. verifies modules, checks formatting, tests with and without the race detector, runs go vet, and verifies CLI help; and
  4. creates a GitHub release for the verified tag with generated release notes.

A v0.x release without a prerelease suffix is a regular GitHub release, but qi remains experimental and pre-1.0.

Prepare main

Use the Go version declared by go.mod and the workflows. Start from a clean, current main branch and confirm it matches the remote:

git switch main
git pull --ff-only origin main

test -z "$(git status --porcelain)"
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"

Run the complete authoritative validation suite without omissions. That suite is kept aligned with the CI and release workflows rather than duplicated here.

Confirm that the latest CI run for main succeeded on the repository Actions page or with GitHub CLI:

gh run list --workflow ci.yml --branch main --limit 1

Do not push a release tag until these checks pass. A pushed Go module version must be treated as immutable even if GitHub release creation has not completed.

Choose and push the version

Fetch existing tags before selecting the next version:

git fetch --tags origin
git tag --list 'v*' --sort=-version:refname

Use a complete vMAJOR.MINOR.PATCH tag. For example, use v0.1.0 for a regular release or v0.2.0-beta.1 for a prerelease. Follow the pre-1.0 compatibility policy in the README.

Create an annotated tag on the prepared commit, inspect it, and push only that tag:

version=v0.1.0 # Replace with the version being released.

git tag -a "$version" -m "Release $version" HEAD
git show --no-patch --decorate "$version"
git push origin "refs/tags/$version"

Do not use git push --tags, which could publish unrelated local tags. The tag push starts the release workflow; do not also run gh release create.

Verify the release

After the run appears, use its ID to watch it complete:

gh run list --workflow release.yml --branch "$version" --limit 1
gh run watch RUN_ID --exit-status
gh release view "$version" --web

Confirm that the release targets the intended commit, prerelease classification is correct, and generated notes are useful. Release notes may be edited without changing the tag.

If the workflow fails

Inspect the failed step first. A transient failure can be retried with:

gh run rerun RUN_ID --failed

Never move, delete, or reuse a version tag after pushing it. Go tooling may discover the tag before the GitHub release exists. If tagged contents need correction, fix main, repeat validation, and publish a new SemVer version. If release creation fails after validation, preserve the tag while investigating or retrying the release job.