# 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