agentleFS
crftwrcrftwr/keyhac/.claude/skills/keyhac-release/SKILL.md

keyhac-release

Skill15 starsChanged 11 days agoMITView on GitHub

Release a new version of Keyhac — confirm the version bump, run the pre-tag checks and account for the standing interactive pass, cut the tag, publish the GitHub Release with a hand-written note, and attach the macOS DMG, Windows zip, skill bundles, and PyPI wheel, and bump the Homebrew cask (crftwr/homebrew-tap). Use when the user says "release Keyhac", "release a patch/minor/major version of Keyhac", or "ship keyhac X.Y.Z" — and also on the Windows machine afterwards, when they say "finish the Keyhac release on Windows" or "attach the Windows artifacts" (step 6: no new tag, just the Windows targets at the existing one).

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run every command from the root of the keyhac checkout.

    line 8
  2. Very specific:

    Do not edit __version__ yourself — make tag bumps, commits, and tags it.

    line 34
  3. Distinctive:

    Write the note to a scratch location outside the repo (it is never committed), then:

    line 150
  4. Distinctive:

    Put the checkout on that tag's commit: git pull when main still sits on the release commit, git checkout vX.Y.Z when it has moved on.

    line 185
  5. Very specific:

    Ask whether to also submit to the Microsoft Store this time: make release-windows-msix.

    line 195

≈ “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 Keyhac

Run every command from the root of the keyhac checkout. One version (__version__ in keyhac/__init__.py) covers both OSes, but the artifacts come from two machines — the DMG builds and notarizes on macOS, the win-x64 and win-arm64 zips and the Store MSIX on Windows — so a release usually finishes across two sessions. Run each OS's targets on that OS and report the other side as remaining; never mark the release done with artifacts missing. The pipeline is documented in doc/dev/packaging.md; the note-writing step (4) is the one part no Makefile target does.

1. Decide the version and confirm it

The single source of truth is __version__ in keyhac/__init__.py (pyproject derives from it via dynamic = ["version"]). Map the request:

  • "patch" → bump Z (2.2.3 → 2.2.4)
  • "minor" → bump Y, reset Z (2.2.3 → 2.3.0)
  • "major" → bump X, reset Y and Z
  • An explicit version wins; preflight also accepts pre-releases (2.3.0a1).

Confirm the number with the user before proceeding. State the mapping explicitly — "current is X.Y.Z, this releases X.Y.Z′" — and wait for a yes (AskUserQuestion in interactive sessions) before the step-2 checks, which cost minutes, and long before make tag, which publishes: a pushed tag, and later a PyPI version that can never be re-uploaded. A misread request must be caught here, not discovered on PyPI.

Do not edit __version__ yourself — make tag bumps, commits, and tags it.

2. Judgment checks before tagging

tools/release_preflight.py (run by make tag) enforces the mechanics: a well-formed version strictly ahead of the current one, pyproject still dynamic, on main, clean tree, tag free, not behind upstream. It also warns — keyhac-specifically — when PuiKit is installed editable: the wheel this release builds depends on the published PuiKit named by the puikit>= pin, so if the code has come to rely on unreleased PuiKit changes, release PuiKit first (its own skill: puikit-release) and raise the pin. Before invoking any of that, do the checks preflight cannot:

  • git log v<current>..origin/main --oneline — everything meant for this release is merged, nothing unexpected rode along. This list is also the raw material for the release note.
  • make release-review — reviews v<current>..origin/main against CLAUDE.md's rules (tools/release_review.py; it includes api-reference-check and check-docs). Report it to the user; fix nothing here, the user decides what is fixed before tagging.
    • Findings (exit 1) are the mechanical rules — OS imports in core/ui, ctypes prototypes, camelCase, and the public API compared against the last tag through tests/data/api_snapshot.txt (a removal or an incompatible signature: additive-only, so each is a stop unless the user moves it to doc/dev/next-major.md). List them as they are.
    • For review lines are pointers, not violations: read each site and give a verdict per line. Its API additions also check step 1 — any of them means at least a minor bump — and, with new deprecations, are the note's raw material.
  • make icons-check — the committed rendered icons must match their SVG sources before they ship.
  • make release-test runs inside make tag (#316): pytest --host-only here, then the whole suite with --desktop in qa-mac (Tart) and qa-win (VMware) on PuiKit and quality-loop as PyPI has them - about ten minutes, so tell the user before starting it. It needs Tart and VMware Fusion on this Mac, and neither VM held by a run-vm here or in XeFM. Since the VMs install PuiKit from PyPI, a release relying on unreleased PuiKit fails here: release PuiKit first. A failure stops the tag: report it with the log under temp/vm-test-<guest>-<time>/, never retry it away. Running it on its own ahead of make tag is fine.
  • The standing interactive pass — doc/dev/testing.md, "The interactive pass before a release". These are live checks no automated harness covers (tray menu and console interactions, IME driving the chooser, mouse feel, tools/bundle_pass.py against a bundle built from the PyPI PuiKit wheel, JIS layout when the keyboard exists), and Claude cannot run them — the agent shell never holds window-server key focus. Ask the user which passes have been done for this release; anything not repeated is skipped and recorded in the conversation, never silently assumed.
  • Draft the release note now (style in step 4). Writing it forces a review of what is actually shipping while the tag is still retractable.

3. The Makefile pipeline

make tag VERSION=x.y.z    # preflight → release-test → bump __version__ → commit
                          # "Releasing x.y.z" → tag vx.y.z → build gate
                          # (sdist+wheel+twine check) → push commit and tag
make release-github       # create the Release (auto body — replaced in step 4)
make release-macos-dmg    # macOS: build.sh (sign/notarize) + create_dmg.sh,
                          # then attach the DMG to the Release
make release-whl          # HEAD must sit on the tag; sdist + wheel → PyPI,
                          # both attached to the Release
make release-skill        # build + attach the skill bundle. NOT optional:
                          # the bundle is the only way a user obtains the
                          # skill — tools/ and the Makefile never ship
make release-status       # read-only: which artifacts have landed

On the Windows machine, from the same checkout at the tag: make release-windows-zip attaches both portable zips (win-x64, win-arm64); make release-windows-msix is the odd one out — it submits one .msixbundle of both architectures to the Microsoft Store, not the GitHub Release, and certification proceeds asynchronously (poll with msstore submission status). Run make from PowerShell here: MSYS2's make started from Git Bash reaches its recipes with most of the environment gone, so gh reads as not logged in and release-status misreports the Release.

The bundle targets (DMG, Windows zip, MSIX) refuse a venv holding anything not installed from a package index — an editable PuiKit included — or outside a requirement (tools/collect_dependencies.py). Before release-macos-dmg and the Windows targets, put the released PuiKit in with make install-puikit PUIKIT_DIR=, and pass PUIKIT_DIR= to the bundle targets too, so a venv refresh on the way does not reinstall the checkout. For anything else the error names, pip install --force-reinstall --no-deps <name>. Never set KEYHAC_BUNDLE_ALLOW_LOCAL for a release build; it is for local development builds. Switch back with make install-puikit afterwards if the user develops against the checkout.

  • make tag commits directly to main — sanctioned for release commits only.
  • Each target is independently re-runnable; release-github is idempotent. The DMG/zip file targets do not rebuild an existing artifact (so a re-upload never re-runs notarization); make macos-dmg / make windows-zip [ARCH=arm64] force a fresh build.
  • Prereqs: [pypi] token in ~/.pypirc, authenticated gh, macos_app/signing.env for sign/notarize, windows_app/store.env + the msstore CLI for the Store submission.

4. The hand-written release note (not in the Makefile)

make release-github creates the Release with GitHub's --generate-notes PR list. That body is a placeholder — replace it with a hand-written note. The model is v2.2.2 (v2.2.3 shipped with only the auto list; don't repeat that).

Style:

  • Body starts ## Keyhac X.Y.Z. Leave the Release title as vX.Y.Z.
  • Anything that changes behavior under an existing user goes first, as a > blockquote addressed to them in second person ("If you turned X on, two things change under you"), saying what breaks, how it fails, and what to do.
  • One bullet per user-visible change: a bold headline in user terms, then prose — the symptom as a user saw it, the cause in a clause, and what now happens. When a bullet is about an attached asset, name the file. Written for Keyhac users, not repo archaeologists.
  • Minor items in one trailing "Also:" sentence.
  • End with **Full Changelog**: https://github.com/crftwr/keyhac/compare/vPREV...vNEW.

Write the note to a scratch location outside the repo (it is never committed), then:

gh release edit vX.Y.Z --notes-file <scratch>/release-note-x.y.z.md

5. After the release

  • make release-status must show all of it: the DMG, both Windows zips, every skill bundle ("N of N attached" — its absence is the one that fails quietly, and a user connecting the MCP endpoint without the skill gets sleep-and-coordinates actions instead of an error), the sdist + wheel, and "PyPI: published".
  • Once the DMG is attached, bump the Homebrew cask. It opens a PR on crftwr/homebrew-tap; merge it when its CI passes. Skip this for a release that ships no DMG:
    brew bump-cask-pr --no-fork --version X.Y.Z crftwr/tap/keyhac
  • List what this machine could not produce (the other OS's artifacts, the Store submission) as explicitly remaining, with the commands the other session must run.

6. Finishing on Windows

The macOS session ends with the Windows artifacts listed as remaining; a later session on the Windows machine enters here ("finish the Keyhac release on Windows"). There is nothing to bump, tag, or confirm a version for — that all happened — but there is still a publish gate: state which release is being finished and get a yes before uploading.

  1. Find the release being finished: git fetch, then make release-status on the latest tag (git describe --tags --abbrev=0 origin/main) — its missing Windows assets are the work. Confirm with the user.
  2. Put the checkout on that tag's commit: git pull when main still sits on the release commit, git checkout vX.Y.Z when it has moved on. The artifacts must be built from the tagged code, not from whatever main has become.
  3. make release-windows-zip — builds both bundles and portable zips, and attaches the zips to the GitHub Release. The arm64 one needs the MSVC ARM64 build tools component. If the collector refuses the venv (a local install, a version below a requirement), bring it to the released versions as in step 3 and rebuild with make windows-zip and make windows-zip ARCH=arm64.
  4. Ask whether to also submit to the Microsoft Store this time: make release-windows-msix. It is a separate publication with its own asynchronous certification (msstore submission status), not a Release asset, so it is a deliberate choice, not a default.
  5. make release-status — the release is finished when everything shows: DMG, both Windows zips, every skill bundle, sdist + wheel, PyPI published.

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.