## Contributing

This document defines how to contribute to Moko Consulting projects.

## Branching Strategy

All repositories follow this branching model:

```
feature/* --> dev --> main
```

| Branch | Purpose | Direct push? |
|--------|---------|-------------|
| `main` | Production/release branch | No -- PR merge only |
| `dev` | Integration branch | No -- PR merge only (CI bot whitelisted) |
| `feature/*` | Feature/bugfix work | Yes -- create freely |
| `rc/*` | Release candidates | No -- PR merge only |
| `alpha/*` | Alpha pre-releases | No -- PR merge only |
| `beta/*` | Beta pre-releases | No -- PR merge only |
| `version/*` | Release archive branches | Auto-created by CI |

### Workflow

1. Create a `feature/*` branch from `dev`
2. Make changes on the feature branch
3. Open a PR from `feature/*` to `dev`
4. After review, merge to `dev`
5. When ready for release, open a PR from `dev` to `main`
6. Merging to `main` triggers the auto-release pipeline

### Automated syncing

- `cascade-dev.yml` automatically forward-merges `main` to `dev` after every push to main
- If there are conflicts, a PR is created automatically

## Prerequisites

Contributors are expected to:

* Have a working understanding of the project's platform (Joomla, Dolibarr, or generic)
* Be familiar with Git and pull request workflows
* Review repository governance documents prior to submitting changes

### Quick Setup

```bash
git clone https://git.mokoconsulting.tech/MokoConsulting/<repo>.git
cd <repo>
git checkout dev
git checkout -b feature/my-change
```

## Coding and Formatting Standards

All contributions must:

* Follow platform coding standards (Joomla, Dolibarr, PHP PSR) where applicable
* Conform to Moko Consulting repository standards for headers, metadata, and file structure
* Keep YAML workflow files ASCII-only (no em dashes, arrows, or emoji)

## Commit Messages

Commit messages should:

* Use conventional commits format: `type(scope): description`
* Types: feat, fix, chore, docs, refactor, test, ci
* Focus on what changed and why
* Include `[skip ci]` suffix for documentation-only changes

## Reporting Issues

Bug reports and enhancement requests should be filed as Gitea issues and include:

* Clear reproduction steps or use cases
* Expected versus actual behavior
* Relevant environment details

Security issues must follow the process in SECURITY.md and must not be reported publicly.

## Review Process

All pull requests are subject to review. Review criteria include:

* Technical correctness
* Alignment with project goals
* Maintainability and clarity
* Risk introduced to release and update processes

## License

By contributing, you agree that your contributions will be licensed under GPL-3.0-or-later, consistent with the rest of the project.