sloane
b04c917ca9
document conventional commit format and best practices for writing clear, consistent commit messages in the jj skill
143 lines
3.9 KiB
Markdown
143 lines
3.9 KiB
Markdown
# Jujutsu Description Style Guide
|
|
|
|
this guide defines the style conventions for commit descriptions in jujutsu repositories.
|
|
|
|
## Header Format
|
|
|
|
the header is a single line in the imperative mood that summarizes the change.
|
|
|
|
### Basic Structure
|
|
|
|
```
|
|
<prefix>: <summary>
|
|
```
|
|
|
|
or with scope:
|
|
|
|
```
|
|
<prefix>(<scope>): <summary>
|
|
```
|
|
|
|
### Capitalization Rules
|
|
|
|
- use lowercase for all text, including the start of sentences
|
|
- **exception**: preserve original capitalization when referencing code elements (module names, class names, API names, functions, etc.)
|
|
|
|
**examples:**
|
|
- `fix: resolve authentication timeout issue`
|
|
- `feat(api): add new GetUser endpoint`
|
|
- `test: ensure AuthManager handles expired tokens`
|
|
- `refactor(protocol): simplify MessageParser logic`
|
|
|
|
### Common Prefixes
|
|
|
|
follow conventional commit conventions:
|
|
|
|
- **feat**: new feature or functionality
|
|
- **fix**: bug fix
|
|
- **test**: adding or modifying tests
|
|
- **refactor**: code restructuring without changing behavior
|
|
- **docs**: documentation changes
|
|
- **style**: formatting, whitespace changes
|
|
- **perf**: performance improvements
|
|
- **build**: build system or dependency changes
|
|
- **ci**: continuous integration configuration
|
|
- **chore**: maintenance tasks
|
|
- **devex**: developer experience improvements
|
|
|
|
### Scope Guidelines
|
|
|
|
the scope provides context about which part of the codebase is affected:
|
|
|
|
- `feat(protocol):` - protocol-related features
|
|
- `test(web):` - web-related tests
|
|
- `fix(api):` - API bug fixes
|
|
- `refactor(cli):` - CLI refactoring
|
|
|
|
scopes are optional but helpful for larger projects.
|
|
|
|
## Body Format (Optional)
|
|
|
|
the body provides additional context about the reasoning behind the change. it should be:
|
|
|
|
- separated from the header by one blank line
|
|
- written in lowercase (except for code references)
|
|
- 1-3 sentences explaining the "why" rather than the "what"
|
|
|
|
**example:**
|
|
```
|
|
feat(workspace): add support for nested workspaces
|
|
|
|
this enables better organization for monorepo structures where multiple
|
|
sub-projects need their own working directories while sharing history.
|
|
```
|
|
|
|
## Lists (Optional)
|
|
|
|
if a commit includes several sub-changes, use a bulleted list after the optional body:
|
|
|
|
- maintain lowercase style (except for code references)
|
|
- use hyphens `-` for list items
|
|
- keep formatting consistent with header and explanation
|
|
|
|
**example:**
|
|
```
|
|
refactor(core): improve change tracking performance
|
|
|
|
this reduces memory usage and speeds up operations on large repositories.
|
|
|
|
- cache ChangeId lookups to avoid repeated hash calculations
|
|
- use lazy evaluation for descendant queries
|
|
- optimize ConflictMarker serialization format
|
|
```
|
|
|
|
## Complete Examples
|
|
|
|
### Simple header only
|
|
```
|
|
fix: handle empty commit messages correctly
|
|
```
|
|
|
|
### With scope
|
|
```
|
|
feat(rebase): add interactive mode for selecting changes
|
|
```
|
|
|
|
### With body
|
|
```
|
|
feat(api): add GetChangesByAuthor query method
|
|
|
|
this allows filtering changes by author name or email, which is useful
|
|
for reviewing team member contributions and generating reports.
|
|
```
|
|
|
|
### With body and list
|
|
```
|
|
refactor(diff): restructure diff generation pipeline
|
|
|
|
the previous implementation had redundant tree traversals and unclear
|
|
separation of concerns.
|
|
|
|
- extract LineComparator into dedicated module
|
|
- introduce DiffFormatter interface for extensibility
|
|
- cache file content hashes during tree walk
|
|
- remove deprecated ThreeWayMerge implementation
|
|
```
|
|
|
|
### Code references preserving capitalization
|
|
```
|
|
test(protocol): add tests for MessageEncoder edge cases
|
|
|
|
- verify MessageEncoder handles empty payloads
|
|
- ensure ProtocolVersion validation rejects invalid versions
|
|
- test SerializationError includes full context
|
|
```
|
|
|
|
## Summary
|
|
|
|
1. always use lowercase, except for code element references
|
|
2. header is single line, imperative mood
|
|
3. use prefixes like `feat:`, `fix:`, `test:`, optionally with scope
|
|
4. body is optional, provides reasoning in 1-3 sentences
|
|
5. lists are optional, maintain consistent style
|
|
6. follow conventional commit conventions
|