diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46e4c20..ea9a5fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,128 +1,141 @@ - - -# Contributing - -Thank you for your interest in contributing to **MokoJoomHero**! - -This repository is governed by **[MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards)** — 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.YY` | Stable frozen snapshot | Demo + RS servers | - -### Development Workflow +## Branching 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) +feature/* ──PR──> dev ──draft PR──> (renamed to rc) ──merge──> main ``` -### Branch Naming +### Step by step -| Prefix | Use | -|--------|-----| -| `dev/XX.YY.ZZ` | Feature development (e.g., `dev/02.00.00/add-extrafields`) | -| `version/XX.YY` | Stable release (auto-created, never manually pushed) | -| `chore/` | Automated sync branches (managed by MokoStandards) | +1. **Create a feature branch** from `dev`: + ```bash + git checkout dev && git pull + git checkout -b feature/my-change + ``` -> **Never use** `feature/`, `hotfix/`, or `release/` prefixes — they are not part of the MokoStandards branch strategy. +2. **Work and commit** on your feature branch. Push to origin. -## Commit Conventions +3. **Open a PR**: `feature/my-change` → `dev`. After review and checks, merge it. -Use [conventional commits](https://www.conventionalcommits.org/): +4. **When ready for release**, open a **draft PR**: `dev` → `main`. + - This automatically renames the source branch to `rc` (release candidate) + - An RC pre-release is built and uploaded + +5. **Alpha and beta branches** are created by manually renaming the branch before the RC stage: + - Rename `dev` to `alpha` for early testing → alpha pre-release is built + - Rename `alpha` to `beta` for feature-complete testing → beta pre-release is built + - When the draft PR is created, the branch is renamed to `rc` + +6. **Once PR checks pass** on the `rc` branch, mark the PR as ready and merge to `main`. + +7. **Merging to main** triggers the stable release pipeline: + - Minor version bump (e.g., `02.09.xx` → `02.10.00`) + - Stability suffix stripped (clean version) + - Gitea release created with ZIP/tar.gz packages + - `updates.xml` updated (Joomla extensions) + - `dev` branch recreated from `main` + +### Branch summary + +| Branch | Purpose | Created by | +|--------|---------|-----------| +| `feature/*` | New features and fixes | Developer | +| `dev` | Integration branch | Auto-recreated after release | +| `alpha` | Alpha pre-release testing | Manual rename from `dev` | +| `beta` | Beta pre-release testing | Manual rename from `alpha` | +| `rc` | Release candidate | Auto-renamed on draft PR to main | +| `main` | Stable releases | Protected, merge only | +| `version/XX.YY.ZZ` | Archived release snapshots | Auto-created by CI | + +### Protected branches + +| Branch | Direct push | Merge via | +|--------|------------|-----------| +| `main` | Blocked (CI bot whitelisted) | PR merge only | +| `dev` | Blocked (CI bot whitelisted) | PR merge from feature/* | +| `rc` | Blocked (CI bot whitelisted) | Auto-created on draft PR | +| `alpha` | Blocked (CI bot whitelisted) | Manual rename | +| `beta` | Blocked (CI bot whitelisted) | Manual rename | +| `feature/*` | Open | N/A (source branch) | + +## Version Policy + +### Format + +All versions use `XX.YY.ZZ` — three two-digit segments, zero-padded: + +- **XX** — Major version (breaking changes) +- **YY** — Minor version (new features, bumped on release to main) +- **ZZ** — Patch version (auto-incremented on every push to dev/feature branches) + +Rollover: patch `99` → `00` increments minor; minor `99` → `00` increments major. + +### Stability suffixes + +Each branch appends a suffix to indicate stability: + +| Branch | Suffix | Example | +|--------|--------|---------| +| `main` | (none) | `02.09.00` | +| `dev` | `-dev` | `02.09.01-dev` | +| `feature/*` | `-dev` | `02.09.01-dev` | +| `alpha` | `-alpha` | `02.09.01-alpha` | +| `beta` | `-beta` | `02.09.01-beta` | +| `rc` | `-rc` | `02.09.01-rc` | + +### Auto version bump + +On every push to `dev`, `alpha`, `beta`, `rc`, or `feature/*`: + +1. Patch version incremented +2. Stability suffix applied based on branch name +3. All version-bearing files updated (manifests, CHANGELOG, PHP headers, etc.) +4. Commit created with `[skip ci]` to avoid loops + +### Version files + +The version tools update all files containing version stamps: + +- `.mokogitea/manifest.xml` (canonical source) +- Joomla XML manifests (`` tag) +- `README.md`, `CHANGELOG.md` (`VERSION:` pattern) +- `package.json`, `pyproject.toml` +- Any text file with a `VERSION: XX.YY.ZZ` label + +Files synced from other repos (with a `# REPO:` header) are not touched. + +## Code Standards + +- **PHP**: PSR-12, tabs for indentation +- **Copyright**: all files must include the Moko Consulting copyright header +- **License**: SPDX identifier `GPL-3.0-or-later` (or as specified per repo) +- **Attribution**: use `Authored-by: Moko Consulting` in commits, not individual names + +## Commit Messages + +Use conventional commit format: ``` -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 +type(scope): short description + +Optional body with context. + +Authored-by: Moko Consulting ``` -**Valid types:** `feat` | `fix` | `docs` | `chore` | `ci` | `refactor` | `style` | `test` | `perf` | `revert` | `build` +Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `ci` -## Pull Request Workflow +Special flags in commit messages: +- `[skip ci]` — skip all CI workflows +- `[skip bump]` — skip auto version bump only -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 +## Reporting Issues -### 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.YY` 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 [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards): - -| Standard | Reference | -|----------|-----------| -| Coding Style | [coding-style-guide.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/coding-style-guide.md) | -| File Headers | [file-header-standards.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/file-header-standards.md) | -| Branching | [branch-release-strategy.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/branch-release-strategy.md) | -| Merge Strategy | [merge-strategy.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/merge-strategy.md) | -| Scripting | [scripting-standards.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/scripting-standards.md) | -| Build & Release | [build-release.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/workflows/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 `.github/workflows/custom/` — they are **never overwritten or deleted** by MokoStandards sync: - -``` -.github/workflows/ -├── deploy-dev.yml ← Synced from MokoStandards -├── auto-release.yml ← Synced from MokoStandards -└── 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) license. +Use the repository's issue tracker with the appropriate template. --- -*This file is synced from [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards). Do not edit directly — changes will be overwritten on the next sync.* +*Moko Consulting *