release

name	release
description	Cut a new Ard version release end-to-end. Creates and pushes a new version tag, waits for the Release Binaries workflow to build and publish the GitHub release, then drafts and updates release notes. Use when a batch of changes is ready to ship as a new version.

Release (Ard)

Overview

Cut a new version of the Ard compiler and publish release notes. This skill handles the full flow: tag → CI → release notes. For notes-only updates to an existing release, use the release-notes skill instead.

In this repo, the release process is driven by pushing a v* git tag. That tag triggers the Release Binaries GitHub Actions workflow, and the workflow creates the GitHub release plus uploaded binaries. The workflow also updates akonwi/homebrew-tap with the new Formula/ard.rb using the HOMEBREW_TAP_TOKEN repository secret.

Prerequisites

• On main, working tree clean, up to date with origin/main
• All PRs intended for this release are already merged
• CI is currently green on main

Sanity-check first:

git status --short --branch
git log --oneline -5

Workflow

1. Pick the next version

List existing tags and decide on the next semver:

git tag --sort=-v:refname | head -5

Version bump rules:

• Patch (0.13.0 → 0.13.1) — bug fixes only, no new APIs
• Minor (0.13.0 → 0.14.0) — new features, stdlib additions, backward-compatible changes
• Major (0.x.y → 1.0.0) — breaking changes (Ard is pre-1.0, so minor bumps may include breaks; call them out clearly)

Quick survey of what's in the release before deciding:

git log <previous-tag>..HEAD --oneline

If ambiguous, ask the user to confirm the version.

2. Tag and push

git tag v<major>.<minor>.<patch>
git push origin v<major>.<minor>.<patch>

3. Wait for the release workflow

Pushing a v* tag triggers .github/workflows/build.yml ("Release Binaries"). It runs tests, builds darwin/linux (amd64/arm64) binaries, creates a GitHub release with the assets attached, and commits the updated Homebrew formula to akonwi/homebrew-tap.

Wait for it to finish before drafting notes (otherwise gh release edit may race with the workflow's gh release create):

gh run watch $(gh run list --workflow "Release Binaries" --limit 1 --json databaseId --jq '.[0].databaseId')

Or poll manually:

gh run list --workflow "Release Binaries" --limit 1

All jobs (test, build (darwin/linux × amd64/arm64), release, update-homebrew-tap) must be green. If the workflow fails, stop and investigate — do not proceed to notes.

4. Draft release notes

Follow the release-notes skill for tone, structure, and publishing:

• Audience: Ard language users, not contributors
• Categories: New Features, Improvements, Bug Fixes, Breaking Changes, Migration Guide (only when relevant)
• Reference previous releases for tone: gh release view <previous-tag>
• End with version tag and commit hash

Generate the diff and classify:

git log <previous-tag>..v<new> --oneline
git diff <previous-tag>..v<new> --stat

Write notes to a temp file (e.g. /tmp/ard-v<new>-notes.md).

5. Publish notes

Update the release the workflow already created:

gh release edit v<new> --notes "$(cat /tmp/ard-v<new>-notes.md)"

Verify:

gh release view v<new>

Notes

• This skill assumes the workflow creates the release. Do not call gh release create — it will conflict with the CI job.
• The Homebrew tap update requires the HOMEBREW_TAP_TOKEN secret to have push access to akonwi/homebrew-tap.
• If the workflow races ahead and you need to rewrite notes later, that's what the release-notes skill is for.
• If the tag was pushed but the workflow hasn't started yet, give GitHub a few seconds and re-query gh run list.
• Do not tag from a feature branch. Always tag from main.