jj-skill/descriptions.md

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