Add `commit-msg` skill + style guide reference
Add a `claude-code` skill for generating commit msgs matching `tractor`'s style, plus a companion style guide derived from analysis of 500 repo commits. Deats, - `SKILL.md` defines the `commit-msg` skill with YAML frontmatter, outlining the generation process, formatting rules, and footer conventions. - `style-guide-reference.md` documents verb frequencies, backtick usage patterns, section markers, abbreviations, and tone from historical commit analysis. (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-codens_aware
parent
70bb77280e
commit
20896bfbab
|
|
@ -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/<timestamp>_<hash>_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.
|
||||||
|
|
@ -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
|
||||||
Loading…
Reference in New Issue