git:20251111.4c3ea09 to git:20260217.1e6769f

---

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

```

## 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.

```

## 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.