commits

Original source / Raw SKILL.md

---
name: commits
description: "Conventional Commits specification. Covers commit structure, types, breaking changes. Keywords: feat, fix, BREAKING CHANGE."
version: "1.0.0"
release_date: "2019-02-21"
---

# Conventional Commits

Specification for structured commit messages that enable automated changelog generation and semantic versioning.

## Quick Reference

### Format

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

[optional body]

[optional footer(s)]
```

### Common Types

| Type       | Purpose                     | SemVer |
| ---------- | --------------------------- | ------ |
| `feat`     | New feature                 | MINOR  |
| `fix`      | Bug fix                     | PATCH  |
| `docs`     | Documentation only          | -      |
| `style`    | Formatting, no code change  | -      |
| `refactor` | Code change, no feature/fix | -      |
| `perf`     | Performance improvement     | -      |
| `test`     | Adding/fixing tests         | -      |
| `build`    | Build system, dependencies  | -      |
| `ci`       | CI configuration            | -      |
| `chore`    | Maintenance tasks           | -      |
| `revert`   | Revert previous commit      | -      |

### Breaking Changes

```
feat!: send email when product shipped

feat(api)!: change response format

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.
```

## Examples

### Simple Commits

```
feat: add user authentication
fix: resolve memory leak in cache
docs: update API documentation
style: format code with prettier
refactor: extract validation logic
perf: optimize database queries
test: add unit tests for auth module
build: upgrade webpack to v5
ci: add GitHub Actions workflow
chore: update dependencies
```

### With Scope

```
feat(auth): add OAuth2 support
fix(parser): handle empty arrays
docs(readme): add installation guide
refactor(api): simplify error handling
```

### With Body

```
fix: prevent request racing

Introduce a request id and reference to latest request.
Dismiss incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue
but are obsolete now.
```

### With Footer

```
fix: correct minor typos in code

Reviewed-by: John Doe
Refs: #123
```

### Breaking Change in Footer

```
feat: allow config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used
for extending other config files.
```

### Breaking Change with ! and Footer

```
chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.
```

### Revert Commit

```
revert: let us never again speak of the noodle incident

Refs: 676104e, a215868
```

## Specification Rules

### MUST

1. Commits MUST be prefixed with a type (`feat`, `fix`, etc.)
2. Type MUST be followed by colon and space
3. Description MUST immediately follow the colon and space
4. `feat` MUST be used for new features
5. `fix` MUST be used for bug fixes
6. Breaking changes MUST be indicated by `!` before `:` OR `BREAKING CHANGE:` footer
7. `BREAKING CHANGE` MUST be uppercase
8. Footer token MUST use `-` instead of spaces (e.g., `Reviewed-by`)

### MAY

1. Scope MAY be provided after type: `feat(parser):`
2. Body MAY be provided after description (blank line between)
3. Footer MAY be provided after body (blank line between)
4. Types other than `feat` and `fix` MAY be used
5. `!` MAY be used with `BREAKING CHANGE:` footer

### Case Sensitivity

- Types: case-insensitive (lowercase recommended for consistency)
- `BREAKING CHANGE`: MUST be uppercase
- `BREAKING-CHANGE`: synonym for `BREAKING CHANGE`

## SemVer Mapping

| Commit Type              | SemVer Bump | Version Change |
| ------------------------ | ----------- | -------------- |
| `fix:`                   | PATCH       | 1.0.0 → 1.0.1  |
| `feat:`                  | MINOR       | 1.0.0 → 1.1.0  |
| `BREAKING CHANGE` or `!` | MAJOR       | 1.0.0 → 2.0.0  |

Breaking changes override type — `fix!:` results in MAJOR bump.

## Changelog Integration

Conventional Commits map directly to [changelog](../changelog/SKILL.md) entries:

| Commit Type       | Changelog Section            |
| ----------------- | ---------------------------- |
| `feat`            | Added                        |
| `fix`             | Fixed                        |
| `perf`            | Changed                      |
| `refactor`        | Changed                      |
| `docs`            | (usually omitted or Changed) |
| `BREAKING CHANGE` | Highlight in Changed/Removed |
| `revert`          | Removed or Fixed             |
| Security fixes    | Security                     |

### Automated Changelog Generation

Tools like `conventional-changelog`, `semantic-release`, or `release-please` can:

- Parse commit messages
- Generate CHANGELOG.md entries
- Determine next version number
- Create releases automatically

See [changelog skill](../changelog/SKILL.md) for CHANGELOG.md format.

## Common Patterns

### Feature Development

```bash
git commit -m "feat(users): add profile page"
git commit -m "feat(users): add avatar upload"
git commit -m "test(users): add profile page tests"
git commit -m "docs(users): document profile API"
```

### Bug Fix with Reference

```bash
git commit -m "fix(auth): resolve session timeout (#142)"
```

### Breaking Change Flow

```bash
# Deprecate first
git commit -m "feat(api): add v2 endpoint

DEPRECATED: /api/v1/users will be removed in next major version"

# Later, remove
git commit -m "feat(api)!: remove v1 endpoints

BREAKING CHANGE: /api/v1/* endpoints have been removed.
Use /api/v2/* instead."
```

## FAQ

### What if commit fits multiple types?

Split into multiple commits when possible. This makes history more organized.

### What if I used wrong type?

Before merge: `git rebase -i` to edit history.
After release: not critical — commit will be missed by automated tools.

### Do all contributors need to use this?

No. Use squash merging and maintainers can write proper message for the merge.

### How to handle reverts?

```
revert: <original commit subject>

Refs: <commit SHA>
```

## Git Configuration

### Commit Template

Set up git to use template:

```bash
git config commit.template .gitmessage
```

See [assets/commit-msg.template](assets/commit-msg.template) for template file.

### Pre-commit Validation

Use [assets/validate-commit-msg.sh](assets/validate-commit-msg.sh) with git hooks or CI.

## Tools

| Tool                                                                                       | Purpose                   |
| ------------------------------------------------------------------------------------------ | ------------------------- |
| [commitlint](https://commitlint.js.org/)                                                   | Lint commit messages      |
| [commitizen](https://commitizen-tools.github.io/commitizen/)                               | Interactive commit helper |
| [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) | Generate changelogs       |
| [semantic-release](https://semantic-release.gitbook.io/)                                   | Automated releases        |
| [release-please](https://github.com/googleapis/release-please)                             | GitHub release automation |

## Critical Prohibitions

- Do not use vague messages ("fix stuff", "update", "wip")
- Do not mix unrelated changes in single commit
- Do not omit breaking change indicators
- Do not use non-standard types without team agreement
- Do not forget blank line between description and body

## Agent Workflow for Commit Messages

**MANDATORY**: Before proposing branch name, commit message, or PR description, the agent MUST:

1. **Check all changed files** using `git status` or `git diff --name-only`
2. **Review actual changes** using `git diff` (staged and unstaged)
3. **Analyze ALL modifications** — not just the files mentioned in conversation
4. **Base proposals on complete changeset** — include all affected files, not partial list

### Workflow Steps

```bash
# Step 1: Get list of all changed files
git status --short

# Step 2: Review actual changes (for unstaged)
git diff

# Step 3: Review staged changes
git diff --staged

# Step 4: Use the complete changeset to propose:
#   - Branch name
#   - Commit message
#   - PR description
```

### Output Format

When user asks for commit message, provide:

1. **Branch name options** (3 variants using conventional prefixes)
2. **Commit message variants** (short/medium/detailed)
3. **PR description** (summarized, not duplicating full changelog)

All proposals MUST be based on the actual `git diff` output, not assumptions.

## Links

- Official specification: https://www.conventionalcommits.org/en/v1.0.0/
- Semantic Versioning: https://semver.org/spec/v2.0.0.html
- Related: [changelog skill](../changelog/SKILL.md) — CHANGELOG.md format

## Templates

- [commit-msg.template](assets/commit-msg.template) — Git commit message template
- [validate-commit-msg.sh](assets/validate-commit-msg.sh) — Validation script


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../changelog/SKILL.md

```markdown
---
name: changelog
description: "Keep a Changelog format. Covers structure, change types, versioning. Keywords: CHANGELOG.md, semver."
version: "1.1.0"
release_date: "2023-03-06"
---

# Changelog

Format specification for CHANGELOG.md based on Keep a Changelog 1.1.0.

## Language Requirement (Mandatory)

- All changelog content MUST be written in English.
- If source information is provided in another language, translate it to English.
- Do not mix languages within the same changelog.

## Quick Reference

### File Header

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
```

### Section Structure

```markdown
## [Unreleased]

### Added

- New feature description

## [1.0.0] - 2024-01-15

### Added

- Feature A
- Feature B

### Changed

- Modified behavior X

### Fixed

- Bug fix Y
```

## Types of Changes

| Type         | Purpose                           |
| ------------ | --------------------------------- |
| `Added`      | New features                      |
| `Changed`    | Changes in existing functionality |
| `Deprecated` | Soon-to-be removed features       |
| `Removed`    | Now removed features              |
| `Fixed`      | Bug fixes                         |
| `Security`   | Vulnerabilities                   |

## Format Rules

### Version Header

```markdown
## [X.Y.Z] - YYYY-MM-DD
```

- Version in brackets, linked to comparison
- Date in ISO 8601 format (YYYY-MM-DD)

### Date-Based Versioning (Alternative)

For projects using date-based versioning instead of semver:

```markdown
## [YYYY-MM-DD]
```

Use current date instead of `[Unreleased]`. This project uses date-based versioning.

### Yanked Releases

```markdown
## [0.0.5] - 2014-12-13 [YANKED]
```

Use when version was pulled due to serious bug or security issue.

### Comparison Links (at file end)

```markdown
[unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/user/repo/releases/tag/v0.9.0
```

## Guiding Principles

1. **For humans, not machines** — Write clear, readable entries
2. **Entry for every version** — Document all releases
3. **Group same types** — Keep Added/Changed/Fixed together
4. **Linkable versions** — Use comparison links
5. **Latest first** — Reverse chronological order
6. **Show release dates** — Use ISO 8601 format
7. **State versioning scheme** — Mention Semantic Versioning if used

## Complete Example

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- New authentication method

## [1.2.0] - 2024-01-20

### Added

- User profile page
- Export to CSV functionality

### Changed

- Improved loading performance by 40%

### Deprecated

- Legacy API endpoint `/api/v1/users` (use `/api/v2/users`)

### Fixed

- Login timeout issue on slow connections

## [1.1.0] - 2024-01-10

### Added

- Dark mode support

### Security

- Fixed XSS vulnerability in comment field

## [1.0.0] - 2024-01-01

### Added

- Initial release with core features
- User registration and login
- Dashboard with analytics

[unreleased]: https://github.com/user/project/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/project/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/project/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/user/project/releases/tag/v1.0.0
```

## Bad Practices

### Commit log diffs

**Don't** dump git log into changelog:

- Full of noise (merge commits, obscure titles)
- Not human-readable
- Mixes important and trivial changes

### Ignoring deprecations

**Don't** skip deprecation notices:

- Users need to know what will break
- Document deprecations before removals
- List breaking changes clearly

### Confusing dates

**Don't** use regional date formats:

- Use ISO 8601: `YYYY-MM-DD`
- Avoids ambiguity (is 01/02/2024 Jan 2 or Feb 1?)

### Inconsistent changes

**Don't** document only some changes:

- Changelog should be single source of truth
- Important changes must be mentioned
- Consistently updated

## Writing Tips

### Good Entry Examples

```markdown
### Added

- OAuth2 authentication with Google and GitHub providers
- Rate limiting for API endpoints (100 req/min)

### Changed

- Database queries now use prepared statements for better security
- Upgraded dependency `lodash` from 4.17.20 to 4.17.21

### Fixed

- Memory leak in WebSocket connection handler
- Race condition in concurrent file uploads
```

### Entry Guidelines

- Review current git changes (diff or changed files list) before drafting; ensure all material changes are covered.
- Start with verb or noun describing the change
- Be specific (mention affected component/endpoint)
- Reference issue/PR numbers when relevant: `(#123)`
- Keep entries concise but informative
- Omit empty sections (do not include a section header if there are no entries for it)

## File Naming

Required: `CHANGELOG.md` (uppercase). Do not use lowercase or alternative names.

Do not use alternative filenames.

## GitHub Releases vs CHANGELOG.md

| Aspect          | GitHub Releases | CHANGELOG.md      |
| --------------- | --------------- | ----------------- |
| Portability     | GitHub-only     | Universal         |
| Discoverability | Less visible    | Standard location |
| Version control | Separate UI     | In repository     |
| Diff links      | Manual setup    | Easy to add       |

GitHub Releases can complement but shouldn't replace CHANGELOG.md.

## Conventional Commits Integration

Changelogs work best with [Conventional Commits](../commits/SKILL.md) format:

| Commit Type       | Changelog Section    |
| ----------------- | -------------------- |
| `feat:`           | Added                |
| `fix:`            | Fixed                |
| `perf:`           | Changed              |
| `refactor:`       | Changed              |
| `docs:`           | (often omitted)      |
| `BREAKING CHANGE` | Highlight in Changed |
| Security fix      | Security             |
| `revert:`         | Removed or Fixed     |

### Automated Generation

Tools that parse Conventional Commits and generate changelogs:

- [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)
- [semantic-release](https://semantic-release.gitbook.io/)
- [release-please](https://github.com/googleapis/release-please)

See [commits skill](../commits/SKILL.md) for commit message format.

## Workflow Integration

### Unreleased Section Pattern

1. Add changes to `## [Unreleased]` during development
2. At release time, rename to `## [X.Y.Z] - YYYY-MM-DD`
3. Create new empty `## [Unreleased]` section
4. Add comparison link for new version

### Pre-commit Checklist

Before release:

- [ ] All notable changes documented
- [ ] Unreleased section moved to version
- [ ] Date added in ISO 8601 format
- [ ] Comparison link added
- [ ] Breaking changes highlighted
- [ ] Deprecations documented

## Critical Prohibitions

- Do not use git log as changelog
- Do not omit breaking changes or deprecations
- Do not use ambiguous date formats
- Do not leave changelog inconsistently updated
- Do not forget to update Unreleased → version at release
- Do not write changelog entries in any language other than English

## README Synchronization

After writing changelog, review the project's main README.md:

1. **Check for outdated information** — features, skills, tools lists
2. **Add new entries** — if changelog introduces new skills, features, or components
3. **Remove deprecated items** — if changelog removes functionality
4. **Update descriptions** — if changelog changes existing functionality

**What to sync:**

- Skills/features tables
- Compatibility lists
- Installation instructions
- Links and references

**What NOT to sync:**

- Changelog content itself (no duplication)
- Version history
- Detailed change descriptions

**Do NOT mention README.md updates in CHANGELOG** — README synchronization is implied and should not be logged as a separate change.

## Links

- Official specification: https://keepachangelog.com/en/1.1.0/
- Semantic Versioning: https://semver.org/spec/v2.0.0.html
- Related: [commits skill](../commits/SKILL.md) — Conventional Commits format

## Templates

- [CHANGELOG.template.md](assets/CHANGELOG.template.md) — Empty template to start
- [CHANGELOG.example.md](assets/CHANGELOG.example.md) — Complete working example

```

### assets/validate-commit-msg.sh

```bash
#!/usr/bin/env bash
# validate-commit-msg.sh - Validate commit message against Conventional Commits
#
# Usage:
#   ./validate-commit-msg.sh "feat(auth): add login"
#   ./validate-commit-msg.sh < .git/COMMIT_EDITMSG
#   echo "fix: bug" | ./validate-commit-msg.sh
#
# Exit codes:
#   0 - Valid commit message
#   1 - Invalid commit message

set -euo pipefail

# Read commit message from argument or stdin
if [[ $# -gt 0 ]]; then
    COMMIT_MSG="$1"
else
    COMMIT_MSG=$(cat)
fi

# Get first line (subject)
SUBJECT=$(echo "$COMMIT_MSG" | head -n1)

# Conventional Commits pattern
# type(scope)!: description
# type!: description
# type(scope): description
# type: description
PATTERN='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9_-]+\))?(!)?: .+$'

# Check if subject matches pattern
if [[ ! "$SUBJECT" =~ $PATTERN ]]; then
    echo "ERROR: Invalid commit message format" >&2
    echo "" >&2
    echo "Subject: $SUBJECT" >&2
    echo "" >&2
    echo "Expected format: <type>(<scope>): <description>" >&2
    echo "" >&2
    echo "Valid types:" >&2
    echo "  feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert" >&2
    echo "" >&2
    echo "Examples:" >&2
    echo "  feat: add user authentication" >&2
    echo "  fix(parser): handle empty arrays" >&2
    echo "  feat!: breaking change" >&2
    echo "  feat(api)!: breaking API change" >&2
    echo "" >&2
    echo "See: https://www.conventionalcommits.org/" >&2
    exit 1
fi

# Check subject length (50 chars recommended, 72 max)
SUBJECT_LENGTH=${#SUBJECT}
if [[ $SUBJECT_LENGTH -gt 72 ]]; then
    echo "WARNING: Subject line is $SUBJECT_LENGTH characters (max 72 recommended)" >&2
fi

# Check for period at end of subject
if [[ "$SUBJECT" =~ \\.$ ]]; then
    echo "WARNING: Subject line should not end with a period" >&2
fi

# Check for BREAKING CHANGE in body/footer
if echo "$COMMIT_MSG" | grep -q "^BREAKING CHANGE:"; then
    echo "INFO: Breaking change detected in footer" >&2
fi

echo "OK: Valid commit message" >&2
exit 0

```