commit-message git:20251111.4c3ea09A

Immutable. This exact content is served forever at /api/v1/blob/a26956392a4ebb74.

---
description: Enforce conventional commit message format
alwaysApply: false
---

# Commit Message Guidelines

This rule ensures consistent commit message formatting following conventional commits standard.

## Format

```
<type>(<scope>): <description>

[optional body]

[optional footer(s)]
```

## Types

Use one of these types:

- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation only changes
- **style**: Changes that don't affect code meaning (formatting, missing semicolons)
- **refactor**: Code change that neither fixes a bug nor adds a feature
- **perf**: Code change that improves performance
- **test**: Adding missing tests or correcting existing tests
- **chore**: Changes to build process or auxiliary tools

## Scope

Optional but recommended. Indicates the area of change:

- **auth**: Authentication/authorization
- **posts**: Post-related features
- **users**: User-related features
- **ui**: UI components
- **core**: Core architecture
- **adr**: Architecture Decision Records
- **deps**: Dependencies

## Description

- Use imperative mood: "add" not "added" or "adds"
- Don't capitalize first letter
- No period at the end
- Maximum 72 characters

## Examples

### Good Examples ✅

```
feat(auth): add recovery phrase login
fix(posts): correct timestamp formatting in feed
docs(adr): add ADR for local-first writes
refactor(core): extract user validation to pipe
test(ui): add snapshot tests for Button component
chore(deps): update next to 15.3.2
style(components): format Avatar with prettier
perf(streams): optimize post stream caching
```

### Bad Examples ❌

```
Added new feature  ❌ (no type, capitalized, vague)
feat: New button   ❌ (capitalized description)
fix posts bug.     ❌ (no scope format, period at end)
Updated stuff      ❌ (no type, vague)
feat(auth): Added the login feature with recovery phrase support  ❌ (past tense, too long)
```

## Multi-line Commits

For complex changes, use body and footer:

```
feat(core): implement local-first write model

This commit introduces local-first writes that commit to Dexie
before syncing to the homeserver, improving perceived responsiveness.

Changes:
- Add LocalWriteService for managing pending writes
- Implement background sync queue
- Add conflict resolution strategy

Refs: #123
See-also: docs/adr/0001-local-first-writes.md
```

## Breaking Changes

Use `BREAKING CHANGE:` in footer:

```
feat(api)!: change post ID format to composite

BREAKING CHANGE: Post IDs now use author:postId format instead of
simple postId. This affects all post-related APIs and database schemas.

Migration guide available in docs/adr/0002-composite-post-ids.md
```

## Common Patterns

### Bug Fixes

```
fix(ui): prevent Button from submitting on hover
fix(core): handle missing user profile gracefully
fix(auth): validate recovery phrase length
```

### Features

```
feat(posts): add image attachment support
feat(ui): implement dark mode toggle
feat(search): add tag-based search
```

### Documentation

```
docs(readme): update setup instructions
docs(adr): add ADR for TTL refresh policy
docs(api): document post creation endpoint
```

### Refactoring

```
refactor(core): extract validation to pipes layer
refactor(ui): migrate Button to Shadcn primitives
refactor(tests): use deterministic time in snapshots
```

## Tips

1. **Think of the commit message as completing this sentence:**
   "If applied, this commit will [your commit message]"
2. **Keep the first line short** - it appears in logs and should be scannable

3. **Use the body for "why"** - the diff shows "what", explain "why" in the body

4. **Reference issues** - use `Refs: #123` or `Closes: #456` in footer

5. **Group related changes** - don't mix refactoring with features

## Verification

Before committing, ask yourself:

- [ ] Does it follow `type(scope): description` format?
- [ ] Is the type appropriate (feat/fix/docs/etc)?
- [ ] Is the description in imperative mood?
- [ ] Is the first line under 72 characters?
- [ ] Does it clearly explain what changed?

## Integration with Tools

### Git Hooks

If using Husky, you can enforce this with `commitlint`:

```bash
npm install --save-dev @commitlint/cli @commitlint/config-conventional
```

### VS Code

Use the Conventional Commits extension for autocomplete.

---

**Remember**: Good commit messages make the project history readable and maintainable. They help future developers (including yourself) understand why changes were made.