Contributing
Changes
- Work on a branch from
main, one change per pull request. - Run
bun run checkbefore pushing: the commit and push hooks run the same gates (privacy, naming, specs, docs, typecheck, tests). - Title the pull request as a conventional commit (
feat: …,fix: …,docs: …,feat!: …for a breaking change). release-please reads these titles from the merge commits to pick the next version and write the changelog.
Releasing
Releases are cut from main by release-please; nobody tags or publishes by hand.
- Merge pull requests into
mainas usual. release-please opens (or updates) a pull request titledchore(main): release X.Y.Zthat bumpspackage.json,hermesPlugin/dashboard/manifest.json,.release-please-manifest.jsonandCHANGELOG.md. - The release workflow adds the release's
Models:line toCHANGELOG.mdand rebuilds the README Releases table on the release PR's branch (bun run docs:releases). If that run failed, runbun run docs:releaseson the branch yourself and push:check:docsfails without it. - Before merging it, bump the
hermesVersiondefault insrc/agentHooks/registry/index.tson the release PR's branch and runbun run check:agentHooks --write, which regenerateshermesPlugin/plugin.yaml; push both. - Merge the release PR.
.github/workflows/release.ymltagsvX.Y.Z, creates the GitHub Release with the notes, and publishes@listeningkit/log@X.Y.Zto npm with provenance. - Check it:
npm view @listeningkit/log version(the registry can lag a few minutes),log version --checkon an install, and a fresh install ending withinstalled log X.Y.Z.
A release that changes a local model changes src/models/manifest (and MODEL_REVISION in python/judge/server.py for the judge) in an ordinary pull request before the release; its README row then says which model changed. Never point a loader at a model without a pinned revision.
The workflow needs the repository secret NPM_TOKEN: an npm automation token with publish rights on @listeningkit/log (Settings → Secrets and variables → Actions). Provenance needs nothing else: the job has id-token: write.
Installs hear about the release within a day through the update check; see updates.md.
Every merge to main whose check passed is also published as a nightly (.github/workflows/nightly.yml, npm dist-tag next, a GitHub prerelease); nobody runs it by hand either.