# Commit Guidelines

## Conventional Changelog Format

Every commit message must follow this structure:

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

<body>

ISSUES CLOSED: #N
```

### Types

| Type       | Description                                      | Version Bump |
|------------|--------------------------------------------------|--------------|
| `feat`     | New feature                                      | MINOR        |
| `fix`      | Bug fix                                          | PATCH        |
| `docs`     | Documentation changes only                       | none         |
| `style`    | Formatting, whitespace — no logic change         | none         |
| `refactor` | Code restructuring — no feature or fix           | none         |
| `test`     | Adding or correcting tests                       | none         |
| `chore`    | Build process, tooling, dependency updates       | none         |
| `perf`     | Performance improvements                         | none         |
| `ci`       | CI/CD configuration changes                      | none         |
| `build`    | Build system or external dependency changes      | none         |
| `revert`   | Reverts a previous commit                        | depends      |

**Breaking changes** (any type) trigger a MAJOR version bump. Indicate with a `!` after the type/scope (`feat!:`) or a `BREAKING CHANGE:` footer.

### First Line Rules

- **Length:** 50–72 characters
- **Mood:** imperative ("add", "fix", "remove" — not "added", "fixes", "removed")
- **No period** at the end
- Format: `<type>(<scope>): <description>`

### Body

- Separated from the first line by a **blank line**
- Explain **what** was done and, more importantly, **why**
- Wrap at ~72 characters per line

### Footer

```
ISSUES CLOSED: #N
```

This line is **required** on every commit. Replace `N` with the issue number.

---

## Commitizen Tool

Commitizen guides you through the commit message format interactively.

```bash
npm install -g commitizen@2.8.6 cz-customizable@4.0.0
git cz  # replaces git commit
```

---

## Pre-commit Setup

```bash
scripts/setup-dev.sh  # installs all pre-commit hooks
```

Hooks automatically validate:

- Code formatting
- Linting
- Static type checking
- Security scanning
- Commit message format

**Never bypass hooks with `--no-verify`.** If a hook fails, fix the underlying issue.

---

## Atomic Commit Rules

1. **One logical change per commit.** One bug fix OR one feature increment — not both.
2. **Related changes together.** If a change requires edits across multiple files, all those files go in one commit.
3. **Never mix cosmetic and functional changes.** Whitespace fixes, renames, and reformatting must be separate commits from logic changes.
4. **Never commit half-done work.** Each commit must represent a complete, coherent unit.
5. **Include tests in the same commit** as the change they test.
6. **Include documentation updates in the same commit** as the code changes they document.
7. **Include changelog updates in the same commit.**
8. **Each commit must build and pass all tests independently.** The repository must never be broken at any commit.
9. **Self-review your diff before committing.** No debug statements, no unrelated edits. Use `git add -p` to stage only intended changes.

---

## Pre-commit Checklist

Run all of the following before every commit (commands shown are Python/nox examples):

- [ ] Lint session → green  (e.g. `nox -s lint`)
- [ ] Type check session → green  (e.g. `nox -s typecheck`)
- [ ] Unit test session → green  (e.g. `nox -s unit_tests`)
- [ ] Coverage session → ≥ 97%  (e.g. `nox -s coverage_report`)
- [ ] Diff reviewed: only intended changes staged (use `git add -p`)
- [ ] Tests included in this commit
- [ ] Documentation updated in this commit
- [ ] Changelog updated

---

## If the Issue Has a Prescribed Commit Message

Some issues include a `## Metadata` section containing an exact commit message first line. **Use it VERBATIM.** Do not paraphrase, reword, or reformat it.

---

## Examples

### Feature commit

```
feat(cli): add tool and validation commands

Implemented `agents tool add/remove/list/show` with YAML config input and
schema validation. Added `agents validation attach/detach` for resource-scoped
validation attachments. Updated CLI reference documentation.

ISSUES CLOSED: #280
```

### Bug fix commit

```
fix(auth): resolve null pointer when parsing empty configuration file

The authentication handler was not checking for empty config before
accessing fields, causing a NullPointerException. Added guard clause
at boundary.

ISSUES CLOSED: #157
```

### Chore commit

```
chore(Commitizen): make repository Commitizen friendly

Added standard Commitizen configuration files to the repo along with all
the custom rules.

ISSUES CLOSED: #31
```
