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:

<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
• All CI checks pass

Code of Conduct

All contributors are expected to follow our Code of Conduct.

Questions?

Open a Question issue or contact us at hello@mokoconsulting.tech.