Contributing to Moko Consulting Projects

Thank you for your interest in contributing. All Moko Consulting repositories follow this universal workflow and version policy.

Branching Workflow

feature/* ──PR──> dev ──draft PR──> (renamed to rc) ──merge──> main

Step by step

Create a feature branch from dev:

git checkout dev && git pull
git checkout -b feature/my-change

Work and commit on your feature branch. Push to origin.
Open a PR: feature/my-change → dev. After review and checks, merge it.
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
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
Once PR checks pass on the rc branch, mark the PR as ready and merge to main.
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/*:

Patch version incremented
Stability suffix applied based on branch name
All version-bearing files updated (manifests, CHANGELOG, PHP headers, etc.)
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 (<version> 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:

type(scope): short description

Optional body with context.

Authored-by: Moko Consulting

Types: feat, fix, chore, docs, style, refactor, test, ci

Special flags in commit messages:

[skip ci] — skip all CI workflows
[skip bump] — skip auto version bump only

Reporting Issues

Use the repository's issue tracker with the appropriate template.

Moko Consulting hello@mokoconsulting.tech

4.6 KiB Raw Permalink Blame History