From dc457e6744e27dcf6cf5910e5444d751deadbe61 Mon Sep 17 00:00:00 2001
From: Jonathan Miller <1+jmiller@noreply.git.mokoconsulting.tech>
Date: Sun, 28 Jun 2026 07:13:39 +0000
Subject: [PATCH] chore: add CONTRIBUTING.md from Template-Joomla

---
 CONTRIBUTING.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..e8697d2
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,88 @@
+<!--
+ 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).