Git Wrapup

When to use

Changes in the working tree are complete and verified, and they are ready to become a released version of the npm package. Typical triggers: a bug fix landed against a tracked issue, a feature is finished, a dependency refresh is done.

This is not a "save my work" skill. A commit here means the version ships.

Pre-wrapup gates

Every item must be true before you touch a version number. If one is red, fix it first — starting wrapup on a broken tree burns the version number and forces an amend.

• Changes exist — uncommitted files, or commits since the last tag
• Work is complete — no half-finished units, no TODO placeholders
• Code simplified — for a diff past ~50 lines or 3+ source files, the code-simplifier pass has run
• bun run devcheck passes — typecheck, ESLint, Prettier, and the CLAUDE.md/AGENTS.md byte-identity check
• bun run test:all passes — clean rebuild plus the full Vitest suite
• Regression test added — a bug fix without a test that fails on the old code is not finished
• Public API reviewed — anything newly exported is in src/index.ts, and no exported signature changed without a matching version bump tier
• Issues updated — GitHub issues this work addresses have a comment saying what landed
• Docs updated — surgical edits to README.md and CLAUDE.md, not rewrites

Steps

1. Review what is shipping

git status
git log v<latest-tag>..HEAD --oneline
git diff --stat
git diff

If the tree is clean and there are no commits since the last tag, halt — nothing to wrap up.

2. Pick the version

Read version from package.json and apply the bump. This package is pre-1.0 but is published and consumed, so treat the public surface as real.

Default to patch. A change to an exported type — PixooResult, Canvas, RGB — is never a patch.

3. Bump the version everywhere

• package.json — version
• README.md — any version badge or install snippet that pins a version
• CLAUDE.md and AGENTS.md — only if they pin a version string; they must stay byte-identical

Catch stragglers (substitute the outgoing version):

rg -n --hidden -g '!node_modules' -g '!dist' -g '!.git' -g '!CHANGELOG.md' '0\.7\.7' .

Historical CHANGELOG.md entries are correct as-is — that is why it is excluded. Resolve every other hit.

4. Author the CHANGELOG entry

CHANGELOG.md is a single hand-maintained file in Keep a Changelog order. Add the new entry directly under the header block, above the previous version.

## [0.7.8] — 2026-08-13

### Fixed

- **canvas:** `drawRect()` now ... (#N).

Rules:

• Never [Unreleased]. Always a concrete version and an ISO date.
• Section order: Added / Changed / Deprecated / Removed / Fixed / Security. Include only sections with entries.
• Every bullet leads with a bold module symbol (**canvas:**, **client:**, **svg-path:**) matching the src/ module it changed.
• One sentence per bullet, two at the absolute most. Name the exported function and what a consumer observes now. Backlink the issue as (#N).
• The diff is the source of truth. Every concrete claim — function name, parameter, error type, threshold — is read out of the changed file, never recalled.
• Cut: mechanism walkthroughs, rationale defense, "X is unchanged" clauses, edge-case inventories.

5. Run the gate

The tree being committed must pass. Run both raw — do not filter the output:

bun run devcheck
bun run test:all

If either fails, halt. Fix, then re-run this step.

6. Commit — group by concern, release artifacts on top

Never git add -A into one blob. Stage each concern explicitly, commit, move on:

1. The work — one commit per concern. Two unrelated fixes are two commits. Work commits do not carry the version.
2. The release commit — last, on top: package.json, CHANGELOG.md, and any README/docs version strings.

git add <paths-for-this-concern>
git commit -m "<subject>"
# repeat per concern; version + changelog land last

The file is the atomic boundary. Never split one file's changes across commits. When a file serves two concerns, it ships whole in the commit of its dominant concern.

Subjects — Conventional Commits, scope = the src/ module:

• Work: fix(canvas): reject non-finite rect dimensions, feat(color): oklch parsing, docs: document discovery timeout
• Release: fix(canvas): 0.7.8 — reject non-finite rect dimensions

When the change and its version bump are inseparable for a small patch, a single commit whose subject leads with the version is correct — that is the shape most of this repo's history takes.

Every commit carries a body of one or two lines — never subject-only, never a paragraph. One sentence of why or the load-bearing constraint:

fix(canvas): reject non-finite rect dimensions

A NaN width reached the fill loop and wrote nothing while reporting success.

Rules:

• Plain -m strings only — no heredoc, no command substitution
• No Co-authored-by or Generated with trailers
• No marketing adjectives ("comprehensive", "robust", "enhanced", "improved")
• No closing keywords (Fixes #N, Closes #N) — they close the issue on push, before the close-out comment recording what shipped. Use bare (#N) backlinks; closing is a deliberate later step.
• Each message stands alone in git log — no chat context, no "as discussed"

7. Cut an annotated tag

git tag -a v<version> --cleanup=whitespace -m "<subject>

- <notable change> (#N)
- <notable change> (#N)"

--cleanup=whitespace is load-bearing: the default strip mode deletes #-leading lines as comments, silently removing markdown headers from the tag body that release-and-publish renders as the GitHub Release.

Format — a headline digest, not a CHANGELOG mirror:

• Subject omits the version. GitHub prepends v<VERSION>: to the release title, so including it stutters.
• Flat bullets only — never Added: / Fixed: section headers.
• Complete at headline granularity: notable changes get a bullet, minor and internal items share one grouped bullet. The CHANGELOG carries depth; the tag carries existence.
• Deps get one line at most, naming only what earns it.
• Issue backlinks as (#N) — they render as links in the Release body.

8. Verify the end state

git log --oneline -8
git show v<version> --stat | head -20
git status

The tag must point at HEAD and the tree must be clean. If not, investigate before going further.

Do not push. This skill stops here.

Constraints

• Local only. No git push, no remote operations. release-and-publish owns those.
• Never git stash — not for a quick check, not for a clean baseline, not for any reason.
• Never destructive — no git reset --hard, git restore ., git clean -f, git checkout -- ..
• Drive every git operation through Bash git.
• If v<version> already exists as a tag, halt and report the version string, the existing tag SHA, and the current HEAD SHA. Do not move or delete tags without explicit authorization.

Checklist

• Diff reviewed end-to-end before the version bump
• Version bumped in package.json and every other file that pins it
• CLAUDE.md and AGENTS.md still byte-identical
• CHANGELOG.md entry added with a concrete version and date, bullets backlinked to issues
• bun run devcheck passes
• bun run test:all passes
• Work grouped into logical commits; version + changelog on top
• Every commit body is one or two lines
• Annotated tag v<version> created with --cleanup=whitespace
• Working tree clean, tag points at HEAD
• Nothing pushed