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
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- quality-loopSkill
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
- Very specific: line 8
Run every command from the root of the keyhac checkout.
- Very specific: line 34
Do not edit __version__ yourself — make tag bumps, commits, and tags it.
- Distinctive: line 150
Write the note to a scratch location outside the repo (it is never committed), then:
- Distinctive: line 185
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.
- Very specific: line 195
Ask whether to also submit to the Microsoft Store this time: make release-windows-msix.
≈ “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.
Files
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— reviewsv<current>..origin/mainagainst CLAUDE.md's rules (tools/release_review.py; it includesapi-reference-checkandcheck-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 todoc/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.
- 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
make icons-check— the committed rendered icons must match their SVG sources before they ship.make release-testruns insidemake tag(#316):pytest --host-onlyhere, then the whole suite with--desktopinqa-mac(Tart) andqa-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 arun-vmhere 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 undertemp/vm-test-<guest>-<time>/, never retry it away. Running it on its own ahead ofmake tagis 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.pyagainst 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 landedOn 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 tagcommits directly tomain— sanctioned for release commits only.- Each target is independently re-runnable;
release-githubis 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, authenticatedgh,macos_app/signing.envfor sign/notarize,windows_app/store.env+ themsstoreCLI 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 asvX.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.md5. After the release
make release-statusmust 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.
- Find the release being finished:
git fetch, thenmake release-statuson the latest tag (git describe --tags --abbrev=0 origin/main) — its missing Windows assets are the work. Confirm with the user. - Put the checkout on that tag's commit:
git pullwhenmainstill sits on the release commit,git checkout vX.Y.Zwhen it has moved on. The artifacts must be built from the tagged code, not from whatevermainhas become. 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 withmake windows-zipandmake windows-zip ARCH=arm64.- 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. make release-status— the release is finished when everything shows: DMG, both Windows zips, every skill bundle, sdist + wheel, PyPI published.
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
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.

