# Contributing

This project follows the
[Tiara Gitflow](https://specs.code.tiararodney.com/tiara-gitflow/)
specification. The vendored copy lives at `vendor/tiara-gitflow-spec.git/`.

## Branches

| Branch | Purpose |
|---|---|
| `main` | Stable. Only receives merge commits from `develop`. |
| `develop` | Integration branch. Issue branches merge here. |
| `feature/<ID>` | Feature work, branched from `develop`. |
| `bugfix/<ID>` | Bug fixes, branched from `develop`. |
| `hotfix/<ID>` | Urgent fixes, branched from `main`. |

Direct commits to `main` are not allowed (only merge commits). Direct commits
to `develop` are allowed only for issue tracker maintenance.

## Issue lifecycle

All work is issue-driven. Issues live in the `TODO` file and are managed with
the `@byteb4rb1e/mime-todo` CLI.

### 1. Create the issue

```bash
npx @byteb4rb1e/mime-todo create --type feature --title "Title" --plan "Description" --module homeostat
```

### 2. Start work

On `develop`, mark the issue as in-progress:

```bash
npx @byteb4rb1e/mime-todo start <ID> --plan "Planned approach"
```

This creates a commit on `develop`. Then create the issue branch:

```bash
git checkout -b feature/<ID>
```

### 3. Implement

Work on the issue branch. Follow the commit conventions below. Keep commits
focused — one logical change per commit.

### 4. Mark done

On the issue branch, mark the issue as done:

```bash
npx @byteb4rb1e/mime-todo done <ID> --summary "What was delivered"
```

### 5. Merge

Merge the issue branch into `develop` with `--no-ff`:

```bash
git checkout develop
git merge --no-ff feature/<ID>
```

## Commit conventions

Commits follow the conventional commit format:

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

### Types

| Type | Use for |
|---|---|
| `feat` | New functionality |
| `fix` | Bug fixes |
| `docs` | Documentation only |
| `refactor` | Code restructuring without behavior change |
| `test` | Adding or modifying tests |
| `chore` | Maintenance (dependencies, CI, tooling) |
| `spec` | Specification changes |

### Rules

- One logical change per commit
- Separate production code from test code in different commits
- No unrelated changes in a single commit
- Respect module boundaries — changes to different modules go in separate
  commits

### Issue lifecycle commits

These are created by the `@byteb4rb1e/mime-todo` CLI:

- `todo(<ID>): in-progress` — on `develop`, describes the planned approach
- `todo(<ID>): done` — on the issue branch, summarizes the delivery

## Code style

- Line length: 80 characters (enforced by autopep8)
- Type annotations: strict mypy
- Format check: `tox -e format`
- Type check: `tox -e lint`
