<!--
 Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 SPDX-License-Identifier: GPL-3.0-or-later
-->

# Contributing to Moko Consulting Projects

Thank you for your interest in contributing! This guide explains our workflow,
conventions, and how to get your changes merged.

## Branching Workflow

We use a **stability-gated** branching model:

```
feature/* ──── PR ───→ dev
                             │ RC cut → rc → main
fix/* ───────── PR ────────────┘
```

1. **Create a branch** from `dev`:
   - `feature/<short-name>` for new functionality
   - `fix/<short-name>` for bug fixes
   - `chore/<short-name>` for maintenance
2. **Open a PR** into `dev`.
3. **CI must pass** before merge.
4. **Release cuts**: `dev → rc → main` are handled by maintainers.

> **Never commit directly to `main` or `dev`.**

## Version Policy

All repositories use the **XX.YY.ZZ** versioning scheme (two-digit segments):

- `XX` -- major (breaking changes)
- `YY` -- minor (new features, backward-compatible)
- `ZZ` -- patch (bug fixes, security patches)

**Stability suffixes** may be appended during pre-release:

| Suffix | Meaning | Example |
|---|---|---|
| `-alpha.N` | Early testing | `06.01.00-alpha.1` |
| `-beta.N`  | Feature complete | `06.01.00-beta.2` |
| `-rc.N`    | Release candidate | `06.01.00-rc.1` |
| *(none)*   | Stable release | `06.01.00` |

## Auto-Bump

Version bumps are **automated** via the `auto-bump` workflow:

- Merges into `dev` trigger a minor/patch bump.
- The workflow updates all version references (manifests, changelog, etc.).
- **Do not manually edit version numbers** -- let the workflow handle it.

## Commit Messages

We follow [Conventional Commits](https://www.conventionalcommits.org/):

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

<optional body>

<optional footer>
```

**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`, `revert`

## Pull Request Checklist

Before submitting a PR, ensure:

- [ ] Branch is based on latest `dev`
- [ ] Commit messages follow conventional commits
- [ ] CHANGELOG.md updated under `[Unreleased]`
- [ ] No `TODO.md`, `.claude/`, `.mcp.json`, or minified files included
- [ ] Code follows [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards)
- [ ] All CI checks pass

## Code of Conduct

All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## Questions?

Open a [Question issue](../../issues/new?template=question.md) or contact
us at [hello@mokoconsulting.tech](mailto:hello@mokoconsulting.tech).