mokoplatform/templates/docs/required/template-CONTRIBUTING.md

Contributing

Thank you for your interest in contributing to {{REPO_NAME}}!

This repository is governed by moko-platform — the authoritative source of coding standards, workflows, and policies for all Moko Consulting repositories.

Branch Strategy

Branch	Purpose	Deploys To
main	Bleeding edge — all development merges here	CI only
dev/XX.YY.ZZ	Feature development	Dev server (version: "development")
version/XX	Stable frozen snapshot	Demo + RS servers

Development Workflow

1. Create branch:   git checkout -b dev/XX.YY.ZZ/my-feature
2. Develop + test    (dev server auto-deploys on push)
3. Open PR → main    (squash merge only)
4. Auto-release      (version branch + tag + GitHub Release created automatically)

Branch Naming

Prefix	Use
dev/XX.YY.ZZ	Feature development (e.g., dev/02.00.00/add-extrafields)
version/XX	Stable release (auto-created, never manually pushed)
chore/	Automated sync branches (managed by moko-platform)

Never use feature/, hotfix/, or release/ prefixes — they are not part of the moko-platform branch strategy.

Commit Conventions

Use conventional commits:

feat(scope): add new extrafield for invoice tracking
fix(sql): correct column type in llx_mytable
docs(readme): update installation instructions
chore(deps): bump enterprise library to 04.02.30

Valid types: feat | fix | docs | chore | ci | refactor | style | test | perf | revert | build

Pull Request Workflow

1. Branch from main using dev/XX.YY.ZZ/description format
2. Bump the patch version in README.md before opening the PR
3. Title must be a valid conventional commit subject line
4. Target main — squash merge only (merge commits are disabled)
5. CI checks must pass before merge

What Happens on Merge

When your PR is merged to main, these workflows run automatically:

1. sync-version-on-merge — auto-bumps patch version, propagates to all file headers
2. auto-release — creates version/XX branch, git tag, and GitHub Release
3. deploy-demo / deploy-rs — deploys to demo and RS servers (if src/** changed)

Coding Standards

All contributions must follow moko-platform:

Standard	Reference
Coding Style	coding-style-guide.md
File Headers	file-header-standards.md
Branching	branch-release-strategy.md
Merge Strategy	merge-strategy.md
Scripting	scripting-standards.md
Build & Release	build-release.md

PR Checklist

• Branch named dev/XX.YY.ZZ/description
• Patch version bumped in README.md
• Conventional commit format for PR title
• All new files have FILE INFORMATION headers
• declare(strict_types=1) in all PHP files
• PHPDoc on all public methods
• Tests pass
• CHANGELOG.md updated
• No secrets, tokens, or credentials committed

Custom Workflows

Place repo-specific workflows in .mokogitea/workflows/custom/ — they are never overwritten or deleted by moko-platform sync:

.mokogitea/workflows/
├── deploy-dev.yml              ← Synced from moko-platform
├── auto-release.yml            ← Synced from moko-platform
└── custom/                     ← Your custom workflows (safe)
    └── my-custom-ci.yml

License

By contributing, you agree that your contributions will be licensed under the GPL-3.0-or-later license.

---

This file is synced from moko-platform. Do not edit directly — changes will be overwritten on the next sync.