From d18742e067e03f4e5f0f783b59d6f612f712f465 Mon Sep 17 00:00:00 2001
From: sloane <git@sloanelybutsurely.com>
Date: Tue, 4 Nov 2025 09:08:48 -0500
Subject: [PATCH] docs: add commit description style guidelines

document conventional commit format and best practices for writing
clear, consistent commit messages in the jj skill
---
 SKILL.md        |   8 +++
 descriptions.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 descriptions.md

diff --git a/SKILL.md b/SKILL.md
index 71cb0fa..f17368a 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -247,6 +247,13 @@ jj abandon <commit>
 - Use `jj op log` to understand repository history
 - Operations include timestamps and descriptions
 
+### Commit Descriptions
+- Use conventional commit format: `feat:`, `fix:`, `test:`, `refactor:`, etc.
+- Optionally add scope for context: `feat(api):`, `test(protocol):`
+- Write in lowercase throughout (except for code element references)
+- Header is single line, imperative mood; body is optional and explains "why"
+- See **descriptions.md** for complete style guidelines and examples
+
 ## Advanced Features
 
 ### Revsets (Detailed reference in revsets.md)
@@ -343,6 +350,7 @@ jj config set --user ui.merge-editor "code --wait --merge"
 ## Resources
 
 ### Supplemental Documentation
+- **descriptions.md** - Commit description style guidelines
 - **revsets.md** - Comprehensive revset language reference
 - **filesets.md** - Complete fileset syntax and patterns
 - **templating.md** - Template language for custom output
diff --git a/descriptions.md b/descriptions.md
new file mode 100644
index 0000000..495ec74
--- /dev/null
+++ b/descriptions.md
@@ -0,0 +1,143 @@
+# 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