# Git Workflow

## Branches

Never commit directly to `main`. Create a branch using one of these prefixes plus a kebab-case description:

| Prefix | Use when |
|---|---|
| `feature/` | Adding or enhancing functionality |
| `fix/` | Fixing a defect before it reaches production |
| `hotfix/` | Fixing a production issue that needs immediate attention |
| `chore/` | Maintenance, cleanup, dependency bumps, tooling |
| `docs/` | Documentation-only changes |
| `refactor/` | Restructuring code without changing behavior |
| `release/` | Preparing a release |

Example: `feature/add-receipt-parser`.

Do not put the Jira key in the branch name. It goes in the PR title (see Pull Requests and Code Review).

Delete your branch after it merges.

## Commits

Commit each logical change on its own. We use [Conventional Commits](https://www.conventionalcommits.org/):

```
type(scope): description
```

- **type** (required): one of the types below
- **scope** (optional): the area affected, lowercase, such as `auth`, `api`, or `deps`
- **description** (required): imperative mood, lowercase, no trailing period

| Type | Use for |
|---|---|
| `feat` | A new feature |
| `fix` | A bug fix |
| `docs` | Documentation only |
| `style` | Formatting with no behavior change |
| `refactor` | Code change that is neither a fix nor a feature |
| `perf` | Performance improvement |
| `test` | Adding or correcting tests |
| `build` | Build system or dependency changes |
| `ci` | CI/CD configuration |
| `chore` | Routine maintenance |
| `revert` | Reverting a previous commit |
| `release` | Cutting a release |

### Commit message rules

- Keep the header under 72 characters.
- Write what the commit does: `add retry logic`, not `added retry logic`.
- Use the body to explain why. The diff already shows what.
- No vague messages: `fix: stuff`, `chore: update code`, and `chore: address review comments` are not acceptable.
- No `WIP` commits on shared branches.

Mark breaking changes with `!` and a `BREAKING CHANGE:` footer:

```
feat(api)!: remove the deprecated /v1/receipts endpoint

BREAKING CHANGE: clients must migrate to /v2/receipts.
```

Optionally reference the Jira ticket in a trailer:

```
feat(payments): add retry logic for transient upstream failures

The payment processor returns 503 during its deployments. Without
retries these surface as user-facing errors. This adds exponential
backoff with 3 attempts.

Refs: DEV-123
```

## Push rules

- Push regularly. Do not sit on unpushed work.
- Never force-push `main`, and never rewrite commits that are already on `main`.
- Never bypass git hooks with `--no-verify`.

## Versioning

We use [Semantic Versioning](https://semver.org/): `MAJOR.MINOR.PATCH`.

| Increment | When |
|---|---|
| `MAJOR` | Breaking changes to an API or contract |
| `MINOR` | New backwards-compatible functionality |
| `PATCH` | Backwards-compatible fixes and dependency updates |

New projects start at `v0.1.0` and move to `v1.0.0` when the interface is stable. How releases are cut is described in CI/CD and Deployments.