agentleFS
BlushyesBlushyes/reef/.agents/skills/releasing-reef/SKILL.md

releasing-reef

Skill84 starsChanged 6 days agoApache-2.0View on GitHub

How to cut a reef release — version bump, tag push, and the GitHub Release notes format. Use when the user says "cut a release", "tag vX.Y.Z", "打个 tag 发布", "发布", "bump version", "release notes", or asks "how do I release reef", "what's the notes format", "is it safe to push this tag". Covers the full pipeline pushing a `v*` tag triggers (multi-platform binary build + npm publish to `@reef-tui/cli` + GitHub Release with assets), the notes convention, and the specific traps we've paid for — Cargo.toml drift, shell escaping when passing notes inline, and how `softprops/action-gh-release` behaves with pre-existing release bodies.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If CI is red on main, fix it before tagging.

    line 56
  2. Very specific:

    If every commit is fix(...) → patch.

    line 76
  3. Distinctive:

    If you lose the race (release already created by the workflow with only auto-notes), fix it up:

    line 105
  4. Very specific:

    Do *not* manually write a ## What's Changed or list every PR — the workflow appends that from GitHub's auto-generated notes.

    line 140
  5. Very specific:

    Consider adding a CI check later: on tag push, assert the crates/reef-tui/Cargo.toml and crates/reef-io/Cargo.toml versions equal …

    line 186
  6. Very specific:

    If you push the tag and walk away, the workflow creates the Release itself (~3 min) with only GitHub's auto-generated notes.

    line 206
  7. Distinctive:

    Does not require retagging or rebuilding.

    line 216

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Releasing reef

Reef releases are driven by git tags matching v*. Pushing such a tag is the single trigger for .github/workflows/release.yml, which does the rest automatically: reef + reef-agent binaries for five targets, npm publish of @reef-tui/cli + five platform subpackages, GitHub Release with assets, and a Homebrew tap update for stable tags. You never run cargo publish, never npm publish by hand, never upload binaries manually. The contract is bump Cargo.toml, commit, tag, push.

What a v* tag push actually runs

.github/workflows/release.yml:

  1. Build matrix — for each target, builds reef-agent first, then reef (cargo build --release --locked -p <crate>). reef-agent goes first because reef-io's build script embeds the freshly-built agent as the upload-fallback blob. Targets:

    • aarch64-apple-darwin, x86_64-apple-darwin
    • x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu (via cross)
    • x86_64-pc-windows-msvc

    Each row uploads two artifacts: reef-<platform> and reef-agent-<platform>. macOS builds use macos-15 for Apple Silicon and macos-15-intel for Intel.

  2. npm platform subpackages — publishes @reef-tui/cli-{darwin-arm64,darwin-x64,linux-arm64,linux-x64,win32-x64}. Each subpackage bundles only the reef binary (the agent is embedded inside it). Each subpackage's package.json version is overwritten at publish time to ${TAG#v}.
  3. npm main package — publishes @reef-tui/cli with optionalDependencies pinned to the same version.
  4. GitHub Release — via softprops/action-gh-release@v2:
    • Attaches ten archives — reef-{darwin-arm64,darwin-x64,linux-arm64,linux-x64}.tar.gz + reef-win32-x64.zip, and the same set prefixed reef-agent-. The standalone agent archives are for users running it outside the upload-fallback path (e.g. preseeding it on a remote host).
    • Has generate_release_notes: true — this appends auto-generated ## What's Changed notes to whatever body the release already has; it does not overwrite a pre-existing body.
  5. Homebrew tap — after github-release succeeds, stable tags call .github/workflows/homebrew.yml. It downloads the four macOS/Linux Reef archives, computes their SHA-256 checksums with scripts/homebrew-formula.py, and commits Formula/reef.rb to Blushyes/homebrew-tap. The formula installs reef and the rf alias. Tags containing - skip this job.

Implications:

  • The source package.json versions (0.0.0) are placeholders — the tag is authoritative for npm.
  • Deleting a tag after push does not unpublish npm packages. You have a 72h unpublish window on npm; beyond that, cut a patch release.
  • NPM_TOKEN repo secret must be valid. Expired token → silent failure on npm steps while the GitHub Release still succeeds.
  • HOMEBREW_TAP_DEPLOY_KEY is a private SSH key stored as a Reef repository secret; its public key must be a write-enabled deploy key on Blushyes/homebrew-tap. Homebrew synchronization can be retried independently with gh workflow run homebrew.yml -f tag=vX.Y.Z. This downloads the existing release assets and updates only the tap; an unchanged formula produces no commit.

Prerequisites

Before touching versions:

git checkout main
git fetch origin
git pull --ff-only
git status                                         # must be clean
gh pr list                                         # nothing should-ship-in-this-release
gh run list --workflow=ci.yml -b main --limit 3    # all green

If CI is red on main, fix it before tagging. A tag on a red commit is a broken release.

Choosing the version

Repo uses pre-1.0 SemVer, loosely:

ChangeBump
Bug fixes only0.x.y+1 (patch)
Any new user-visible feature0.x+1.0 (minor)
Breaking change (pre-1.0)0.x+1.0 — minor still; breaking is expected below 1.0
Stability commitment1.0.0 — deliberate, not as part of a routine release

Skim the commit list to classify:

PREV=v0.4.0
git log --oneline --no-merges "${PREV}..main"

If every commit is fix(...) → patch. One or more feat(...) → minor. When in doubt, ask the user — don't guess.

Procedure

PREV=v0.4.0       # last tag — sanity-check with `git describe --tags --abbrev=0`
NEW=v0.5.0        # this release

# 1. Bump Cargo.toml files. `cargo build` re-runs to sync Cargo.lock entries.
sed -i '' 's/^version = ".*"/version = "'"${NEW#v}"'"/' crates/reef-tui/Cargo.toml crates/reef-io/Cargo.toml   # macOS BSD sed
cargo build
git diff --stat crates/reef-tui/Cargo.toml crates/reef-io/Cargo.toml Cargo.lock

# 2. Release commit — on main, pre-tag.
git add crates/reef-tui/Cargo.toml crates/reef-io/Cargo.toml Cargo.lock
git commit -m "chore: release ${NEW}"
git push origin main

# 3. Annotated tag on the release commit, push it.
git tag -a "${NEW}" -m "${NEW}"
git push origin "${NEW}"

# 4. Write notes to a file, then pre-create the Release before the workflow finishes.
$EDITOR /tmp/release-notes.md
gh release create "${NEW}" --title "${NEW}" --notes-file /tmp/release-notes.md

Step 4 races the workflow's release-creation step (the github-release job runs after the ~3-minute build matrix). Pre-creating with gh release create wins the race and the workflow's action finds the existing release, attaches the binaries, and appends ## What's Changed to your body. Your handwritten Highlights stay at the top.

If you lose the race (release already created by the workflow with only auto-notes), fix it up:

gh release edit "${NEW}" --notes-file /tmp/release-notes.md

Note: --notes-file, not --notes "...". Inline heredoc gets mangled by shell escaping — see Pitfalls below.

Release notes format

Template (/tmp/release-notes.md):

## Highlights

- **Feature name** — one-sentence user-facing pitch. (#PR)

## Fixes

- Short description of the fix. Closes #ISSUE. (#PR)

**Full changelog**: https://github.com/Blushyes/reef/compare/vPREV...vNEW

Rules:

  • Headings: ## Highlights (new user-visible features) → ## Fixes. Add ## Breaking changes at the top if any.
  • One bullet per user-visible change, not one per commit. Fold related commits into a single bullet.
  • Bold the feature name at the start of a Highlights bullet; plain prose in Fixes.
  • Closes #N inline for user-reported issues the release resolves.
  • (#PR) at the end of every bullet — helps readers jump into the discussion.
  • Always end with the compare link — it's the exhaustive view.
  • No emojis.
  • Omit chore:, refactor:, test:, ci:, docs: unless they change user-visible behavior. The tag's auto-appended ## What's Changed will list all PRs regardless.

Do not manually write a ## What's Changed or list every PR — the workflow appends that from GitHub's auto-generated notes. Don't duplicate.

Example — the actual v0.5.0 notes we shipped:

## Highlights

- **Vim-style in-panel search** — `/` / `?` to search, `n` / `N` to jump between matches, works across all three tabs. (#11)
- **Open files in `$EDITOR`** — press <kbd>Enter</kbd> on a file in the Files tab, or `e` on a changed file in the Git tab, to hand off to your configured editor. (#12)

## Fixes

- Scrolling is no longer trapped on the opened file in the **Files** tab — the mouse wheel now scrolls the tree freely again. Closes #10. (#13)
- Same fix applied to the **Graph** tab so the commit list scroll isn't snapped back to the selected commit. (#14)

**Full changelog**: https://github.com/Blushyes/reef/compare/v0.4.0...v0.5.0

Post-release verification

gh run watch --exit-status                         # wait for release.yml to finish
gh release view "${NEW}"                           # binaries all listed?
npm view @reef-tui/cli version                     # matches ${NEW#v}?
npm view @reef-tui/cli-darwin-arm64 version        # and subpackages
gh run list --repo Blushyes/homebrew-tap --limit 3 # formula installation checks
brew update
brew info blushyes/tap/reef                        # version matches the release

Expected assets on the Release (10 total):

  • reef-darwin-arm64.tar.gz, reef-darwin-x64.tar.gz
  • reef-linux-arm64.tar.gz, reef-linux-x64.tar.gz
  • reef-win32-x64.zip
  • reef-agent-darwin-arm64.tar.gz, reef-agent-darwin-x64.tar.gz
  • reef-agent-linux-arm64.tar.gz, reef-agent-linux-x64.tar.gz
  • reef-agent-win32-x64.zip

If any are missing, the matrix job for that target failed — open gh run view <run_id>, check which job, re-run just the failed jobs with gh run rerun <run_id> --failed. A partial build does not block the npm publish jobs that already ran successfully, so your npm package may be live without the missing platform. Decide: rerun (good if the failure was transient) or cut a patch release (if the failure is real). Note: because reef-io embeds reef-agent, a reef-agent build failure cascades into the reef build for that target — the two binaries for a given platform fail or succeed together.

Pitfalls we've paid for

Cargo.toml drift

Before v0.5.0, Cargo.toml sat at version = "0.1.0" across seven tags from v0.1.0 → v0.4.0. Every release commit must bump crates/reef-tui/Cargo.toml, crates/reef-io/Cargo.toml, and Cargo.lock together. If you see version = "0.x.y" where x.y is older than the latest tag on main, the previous release skipped the bump — fix it in your release commit.

Consider adding a CI check later: on tag push, assert the crates/reef-tui/Cargo.toml and crates/reef-io/Cargo.toml versions equal ${GITHUB_REF_NAME#v} before the publish jobs.

Shell escaping in --notes

# DON'T — backticks and $ get interpreted by the outer "..." even with
# a single-quoted heredoc inside. Notes ship with literal \` and \$.
gh release create vX.Y.Z --notes "$(cat <<'EOF'
...
EOF
)"

# DO — write to a file first.
gh release create vX.Y.Z --notes-file /tmp/release-notes.md

v0.5.0 shipped with \$EDITOR`visible in the rendered body — not a disaster but ugly. Use--notes-fileevery time there's a code fence, backtick, or$` in the notes.

Racing the workflow

If you push the tag and walk away, the workflow creates the Release itself (~3 min) with only GitHub's auto-generated notes. Write and pre-create your notes immediately after git push origin vX.Y.Z, or fix up afterwards with gh release edit --notes-file.

macOS dtolnay/rust-toolchain@stable DNS flakes

The Install Rust toolchain step on macOS runners can fail with failed to lookup address information resolving static.rust-lang.org. Transient. Rerun just the failed job:

gh run rerun <run_id> --failed

Does not require retagging or rebuilding.

Don't delete a pushed tag to "undo"

Deleting the tag from GitHub does not unpublish npm packages. If you catch a bad tag within 72h, npm unpublish @reef-tui/cli@$VER and each subpackage (5 of them). Beyond 72h, cut a patch release that reverts the offending commit — npm has no public unpublish after that window.

Prereleases

The current pipeline does not branch on prerelease tags. Pushing v0.6.0-rc.1 would publish it to npm under the default latest dist-tag, which is wrong for a prerelease. If prereleases become needed, guard the publish jobs on !contains(github.ref, '-') or add a --tag next flag to npm publish. For now: don't prerelease through this pipeline.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.