diff --git a/.claude/skills/commit-msg/SKILL.md b/.claude/skills/commit-msg/SKILL.md new file mode 100644 index 00000000..445eb33a --- /dev/null +++ b/.claude/skills/commit-msg/SKILL.md @@ -0,0 +1,73 @@ +--- +name: commit-msg +description: Generate git commit messages following project style. + Use when user wants to create a commit or asks for a commit message. +allowed-tools: + - Bash + - Read + - Write +--- + +When generating commit messages, always follow this process: + +1. **Gather context**: Run, `~/repos/claude_wks/commit_gen.py` + to get staged changes, recent commits, and style guide rules + +2. **Analyze the diff**: Understand what files changed and the nature + of the changes (new feature, bug fix, refactor, etc.) + +3. **Write the commit message** following these rules: + +**Use the accompanying style guide:** +- Use the style guide `./style-guide-reference.md` for more details + on how to write the message based on analysis of past commits in + this repo. + +**Subject Line Format:** +- Present tense verbs: Add, Drop, Fix, Use, Move, Adjust, etc. +- Target 50 chars (hard max: 67) +- Backticks around ALL code elements (classes, functions, modules, vars) +- Specific about what changed + +**Body Format (optional - keep simple if warranted):** +- Max 67 char line length +- Use `-` bullets for lists +- Section markers: `Also,` `Deats,` `Other,` `Further,` +- Abbreviations: msg, bg, ctx, impl, mod, obvi, tn, fn, bc, var, prolly +- Casual yet technically precise tone +- Never write lines with only whitespace + +**Common Opening Patterns:** +- New features: "Add `feature` to `module`" +- Removals: "Drop `attr` from `class`" +- Bug fixes: "Fix `issue` in `function`" +- Code moves: "Move `thing` to `new_location`" +- Adoption: "Use `new_tool` for `task`" +- Minor tweaks: "Adjust `behavior` in `component`" + +4. **Write to TWO files**: + - `.claude/__commit_msg.md` (timestamp from `date + --iso-8601=seconds`, hash from `git log -1 --format=%h` first + 7 chars) + - `.claude/git_commit_msg_LATEST.md` (overwrite) + +5. **Always include credit footer**: + +When no part of the patch was written by `claude`, +``` +(this commit msg was generated in some part by [`claude-code`][claude-code-gh]) + +[claude-code-gh]: https://github.com/anthropics/claude-code +``` + +and when some or all of the patch was written by `claude` instead +use, + +``` +(this patch was generated in some part by [`claude-code`][claude-code-gh]) + +[claude-code-gh]: https://github.com/anthropics/claude-code +``` + +Keep it concise. Match the tone of recent commits. For simple +changes, use subject line only. diff --git a/.claude/skills/commit-msg/style-guide-reference.md b/.claude/skills/commit-msg/style-guide-reference.md new file mode 100644 index 00000000..97445d29 --- /dev/null +++ b/.claude/skills/commit-msg/style-guide-reference.md @@ -0,0 +1,227 @@ +# Commit Message Style Guide for `tractor` + +Analysis based on 500 recent commits from the `tractor` repository. + +## Core Principles + +Write commit messages that are technically precise yet casual in +tone. Use abbreviations and informal language while maintaining +clarity about what changed and why. + +## Subject Line Format + +### Length and Structure +- Target: ~49 chars (avg: 48.7, max: 50 preferred) +- Use backticks around code elements (72.2% of commits) +- Rarely use colons (5.2%), except for file prefixes +- End with '?' for uncertain changes (rare: 0.8%) +- End with '!' for important changes (rare: 2.0%) + +### Opening Verbs (Present Tense) + +Most common verbs from analysis: +- `Add` (14.4%) - wholly new features/functionality +- `Use` (4.4%) - adopt new approach/tool +- `Drop` (3.6%) - remove code/feature +- `Fix` (2.4%) - bug fixes +- `Move`/`Mv` (3.6%) - relocate code +- `Adjust` (2.0%) - minor tweaks +- `Update` (1.6%) - enhance existing feature +- `Bump` (1.2%) - dependency updates +- `Rename` (1.2%) - identifier changes +- `Set` (1.2%) - configuration changes +- `Handle` (1.0%) - add handling logic +- `Raise` (1.0%) - add error raising +- `Pass` (0.8%) - pass parameters/values +- `Support` (0.8%) - add support for something +- `Hide` (1.4%) - make private/internal +- `Always` (1.4%) - enforce consistent behavior +- `Mk` (1.4%) - make/create (abbreviated) +- `Start` (1.0%) - begin implementation + +Other frequent verbs: `More`, `Change`, `Extend`, `Disable`, `Log`, +`Enable`, `Ensure`, `Expose`, `Allow` + +### Backtick Usage + +Always use backticks for: +- Module names: `trio`, `asyncio`, `msgspec`, `greenback`, `stackscope` +- Class names: `Context`, `Actor`, `Address`, `PldRx`, `SpawnSpec` +- Method names: `.pause_from_sync()`, `._pause()`, `.cancel()` +- Function names: `breakpoint()`, `collapse_eg()`, `open_root_actor()` +- Decorators: `@acm`, `@context` +- Exceptions: `Cancelled`, `TransportClosed`, `MsgTypeError` +- Keywords: `finally`, `None`, `False` +- Variable names: `tn`, `debug_mode` +- Complex expressions: `trio.Cancelled`, `asyncio.Task` + +Most backticked terms in tractor: +`trio`, `asyncio`, `Context`, `.pause_from_sync()`, `tn`, +`._pause()`, `breakpoint()`, `collapse_eg()`, `Actor`, `@acm`, +`.cancel()`, `Cancelled`, `open_root_actor()`, `greenback` + +### Examples + +Good subject lines: +``` +Add `uds` to `._multiaddr`, tweak typing +Drop `DebugStatus.shield` attr, add `.req_finished` +Use `stackscope` for all actor-tree rendered "views" +Fix `.to_asyncio` inter-task-cancellation! +Bump `ruff.toml` to target py313 +Mv `load_module_from_path()` to new `._code_load` submod +Always use `tuple`-cast for singleton parent addrs +``` + +## Body Format + +### General Structure +- 43.2% of commits have no body (simple changes) +- Use blank line after subject +- Max line length: 67 chars +- Use `-` bullets for lists (28.0% of commits) +- Rarely use `*` bullets (2.4%) + +### Section Markers + +Use these markers to organize longer commit bodies: +- `Also,` (most common: 26 occurrences) +- `Other,` (13 occurrences) +- `Deats,` (11 occurrences) - for implementation details +- `Further,` (7 occurrences) +- `TODO,` (3 occurrences) +- `Impl details,` (2 occurrences) +- `Notes,` (1 occurrence) + +### Common Abbreviations + +Use these freely (sorted by frequency): +- `msg` (63) - message +- `bg` (37) - background +- `ctx` (30) - context +- `impl` (27) - implementation +- `mod` (26) - module +- `obvi` (17) - obviously +- `tn` (16) - task name +- `fn` (15) - function +- `vs` (15) - versus +- `bc` (14) - because +- `var` (14) - variable +- `prolly` (9) - probably +- `ep` (6) - entry point +- `OW` (5) - otherwise +- `rn` (4) - right now +- `sig` (4) - signal/signature +- `deps` (3) - dependencies +- `iface` (2) - interface +- `subproc` (2) - subprocess +- `tho` (2) - though +- `ofc` (2) - of course + +### Tone and Style + +- Casual but technical (use `XD` for humor: 23 times) +- Use `..` for trailing thoughts (108 occurrences) +- Use `Woops,` to acknowledge mistakes (4 subject lines) +- Don't be afraid to show personality while being precise + +### Example Bodies + +Simple with bullets: +``` +Add `multiaddr` and bump up some deps + +Since we're planning to use it for (discovery) +addressing, allowing replacement of the hacky (pretend) +attempt in `tractor._multiaddr` Bp + +Also pin some deps, +- make us py312+ +- use `pdbp` with my frame indexing fix. +- mv to latest `xonsh` for fancy cmd/suggestion injections. + +Bump lock file to match obvi! +``` + +With section markers: +``` +Use `stackscope` for all actor-tree rendered "views" + +Instead of the (much more) limited and hacky `.devx._code` +impls, move to using the new `.devx._stackscope` API which +wraps the `stackscope` project. + +Deats, +- make new `stackscope.extract_stack()` wrapper +- port over frame-descing to `_stackscope.pformat_stack()` +- move `PdbREPL` to use `stackscope` render approach +- update tests for new stack output format + +Also, +- tweak log formatting for consistency +- add typing hints throughout +``` + +## Special Patterns + +### WIP Commits +Rare (0.2%) - avoid committing WIP if possible + +### Merge Commits +Auto-generated (4.4%), don't worry about style + +### File References +- Use `module.py` or `.submodule` style +- Rarely use `file.py:line` references (0 in analysis) + +### Links +- GitHub links used sparingly (3 total) +- Prefer code references over external links + +## Footer + +The default footer should credit `claude` (you) for helping generate +the commit msg content: + +``` +(this commit msg was generated in some part by [`claude-code`][claude-code-gh]) + +[claude-code-gh]: https://github.com/anthropics/claude-code +``` + +Further, if the patch was solely or in part written by `claude`, instead +add: + +``` +(this patch was generated in some part by [`claude-code`][claude-code-gh]) + +[claude-code-gh]: https://github.com/anthropics/claude-code +``` + +## Summary Checklist + +Before committing, verify: +- [ ] Subject line uses present tense verb +- [ ] Subject line ~50 chars (hard max 67) +- [ ] Code elements wrapped in backticks +- [ ] Body lines ≤67 chars +- [ ] Abbreviations used where natural +- [ ] Casual yet precise tone +- [ ] Section markers if body >3 paragraphs +- [ ] Technical accuracy maintained + +## Analysis Metadata + +``` +Source: tractor repository +Commits analyzed: 500 +Date range: 2019-2025 +Analysis date: 2026-02-08 +``` + +--- + +(this style guide was generated by [`claude-code`][claude-code-gh] +analyzing commit history) + +[claude-code-gh]: https://github.com/anthropics/claude-code