# Conventional Commits

Structured commit message format for version control that provides clear, readable project history.

## When to use[​](#when-to-use "Direct link to When to use")

Use when creating git commits, writing commit messages, or following version control workflows

## Install the skill[​](#install-the-skill "Direct link to Install the skill")

```
npx skills add tigrisdata/skills --skill conventional-commits
```

This page is generated from [`skills/conventional-commits/SKILL.md`](https://github.com/tigrisdata/skills/blob/main/skills/conventional-commits/SKILL.md) in the [tigrisdata/skills](https://github.com/tigrisdata/skills) repository.

## Overview[​](#overview "Direct link to Overview")

The Conventional Commits specification provides:

* **Automated changelog generation** - Tools can parse commits to generate CHANGELOG.md
* **Semantic versioning** - Commit types map to version bumps (feat → minor, breaking → major)
* **Clear project history** - Standardized format makes git log readable
* **Automated releases** - CI/CD can trigger releases based on commit types

## Quick Reference[​](#quick-reference "Direct link to Quick Reference")

| Type       | Use For                                | Version Bump |
| ---------- | -------------------------------------- | ------------ |
| `feat`     | New feature                            | MINOR        |
| `fix`      | Bug fix                                | PATCH        |
| `docs`     | Documentation only                     | PATCH        |
| `style`    | Formatting, no logic change            | PATCH        |
| `refactor` | Code restructuring, no behavior change | PATCH        |
| `perf`     | Performance improvement                | PATCH        |
| `test`     | Adding or updating tests               | PATCH        |
| `build`    | Build system or dependencies           | PATCH        |
| `ci`       | CI/CD configuration                    | PATCH        |
| `chore`    | Maintenance, no user-facing change     | PATCH        |
| `revert`   | Revert a previous commit               | PATCH        |

## Format[​](#format "Direct link to Format")

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



[optional body]



[optional footer(s)]
```

**Rules:**

* Type is required
* Scope is optional - use parenthesized section affected: `(api)`, `auth)`, `parser)`
* Description is required
* Keep description concise, imperative mood, lowercase, no trailing period
* Body and footer are optional
* Separate subject from body with blank line
* Wrap body at 72 characters

## Examples[​](#examples "Direct link to Examples")

```
feat: add user authentication



Implement JWT-based authentication with login/logout endpoints.

Includes password hashing and session management.



Closes: #123
```

```
fix(api): handle null response from server



Previous implementation crashed when server returned null.

Now returns empty result set.



Assisted-by: GLM 4.6 via Claude Code
```

```
feat(storage)!: change bucket listing API



BREAKING CHANGE: bucket list now returns async iterator

instead of array. Update all callers to use for-await.
```

```
refactor(core): simplify error handling



Consolidate duplicate error handlers into single utility.

No behavior changes - internal cleanup only.
```

```
revert: feat(auth): add OAuth support



This reverts commit 8b5a1c2. OAuth provider changed

their API and we need to redesign integration.
```

## Breaking Changes[​](#breaking-changes "Direct link to Breaking Changes")

Indicate breaking changes in two ways:

**Option 1**: Add `!` after type/scope

```
feat(api)!: remove deprecated endpoint
```

**Option 2**: Add `BREAKING CHANGE:` footer

```
feat(api): remove deprecated endpoint



BREAKING CHANGE: endpoint no longer exists. Use newEndpoint instead.
```

## AI Attribution[​](#ai-attribution "Direct link to AI Attribution")

AI agents must disclose their assistance in the commit footer:

```
Assisted-by: [Model Name] via [Tool Name]
```

Examples:

* `Assisted-by: GLM 4.6 via Claude Code`
* `Assisted-by: Claude Opus 4.5 via claude.ai`

## Common Mistakes[​](#common-mistakes "Direct link to Common Mistakes")

| Mistake                              | Why Wrong                 | Correct                      |
| ------------------------------------ | ------------------------- | ---------------------------- |
| `Added login feature`                | Past tense, capitalized   | `feat: add login feature`    |
| `fix bug.`                           | Trailing period           | `fix: resolve login error`   |
| `update`                             | Missing type              | `chore: update dependencies` |
| `feature:add-auth`                   | Missing space after colon | `feat: add authentication`   |
| `FEAT: big change`                   | Uppercase type            | `feat: add authentication`   |
| Multi-line description no blank line | No separation             | Add blank line after subject |

## Body Guidelines[​](#body-guidelines "Direct link to Body Guidelines")

* **What**: Motivation for the change (vs. code comments describe HOW)
* **Contrast**: Explain the WHY and WHAT, not code details
* **Wrap at 72 characters** for readability in git log

```
feat(summarization): add support for nested bullet points



Previous implementation only flattened all content. Now preserves

hierarchy by respecting indentation levels. Users can now create

structured summaries with parent-child relationships.



Closes: #456
```

## Footer Guidelines[​](#footer-guidelines "Direct link to Footer Guidelines")

Use footers for:

* **Breaking changes**: `BREAKING CHANGE: detailed explanation`
* **Issue references**: `Closes: #123`, `Fixes: #456`, `Refs: #789`
* **AI attribution**: `Assisted-by: Model via Tool`

Multiple footers separated by blank lines:

```
feat: add batch upload



Implements multipart upload for large files.



BREAKING CHANGE: upload() signature changed - now requires options object

Closes: #123

Assisted-by: GLM 4.6 via Claude Code
```

## Git Commit Flags[​](#git-commit-flags "Direct link to Git Commit Flags")

**Required flag:** Always use `--signoff` when committing:

```
git commit --signoff -m "feat: add user authentication"
```

The `--signoff` flag adds a `Signed-off-by` trailer to the commit message, indicating the committer has certified the commit follows developer certificate of origin (DCO).

## Testing Your Commit[​](#testing-your-commit "Direct link to Testing Your Commit")

Before committing, verify:

1. <!-- -->
   Type is from allowed list
2. <!-- -->
   Description is imperative mood (add, fix, update)
3. <!-- -->
   Description is lowercase
4. <!-- -->
   No trailing period on description
5. <!-- -->
   Breaking changes marked with `!` or footer
6. <!-- -->
   AI attribution included (if applicable)
7. <!-- -->
   Body explains WHY not HOW
8. <!-- -->
   Using `--signoff` flag
