---
name: conventional-commits-and-pr
description: Use when generating commit messages, structuring pull request descriptions, or maintaining changelogs following the Conventional Commits specification.
---

# Conventional Commits & Pull Request Documentation

## Purpose
Format commit messages and PR descriptions consistently according to the Conventional Commits 1.0.0 specification for automated versioning and transparent project history.

## Commit Message Format

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Types
- **`feat`**: A new feature (correlates with `MINOR` in Semantic Versioning).
- **`fix`**: A bug fix (correlates with `PATCH` in Semantic Versioning).
- **`docs`**: Documentation only changes.
- **`style`**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
- **`refactor`**: A code change that neither fixes a bug nor adds a feature.
- **`perf`**: A code change that improves performance.
- **`test`**: Adding missing tests or correcting existing tests.
- **`build`**: Changes that affect the build system or external dependencies.
- **`ci`**: Changes to CI configuration files and scripts.
- **`chore`**: Other changes that don't modify src or test files.

### Breaking Changes
Indicated by an exclamation mark `!` after the type/scope or `BREAKING CHANGE:` in the footer (correlates with `MAJOR` in SemVer):
```
feat(api)!: drop legacy v1 authentication endpoints
```

## Pull Request Template Structure

```markdown
## Summary
Concise 2-3 sentence overview of what this PR accomplishes and why.

## Key Changes
- **Area 1:** Bullet point explaining concrete change.
- **Area 2:** Bullet point explaining concrete change.

## Verification & Testing
- [x] Unit tests passing (`pnpm test`)
- [x] Tested locally with [scenario description]
```