🌱 Branching Model
We follow a structured Git Flow model, customised for versioning, feature isolation, and hotfix traceability.
| Branch | Purpose |
|---|---|
main | Production-ready, tagged releases only |
develop | Active development and integration branch |
feature/* | New feature branches (e.g., feature/f21-email-templates) |
release/* | Pre-release stabilization, version bump, testing |
hotfix/* | Urgent patches directly on production |
support/* | Maintenance for legacy major versions (e.g., support/1.x) |
🔁 Workflow Phases
🧱 1. Start a Feature
git checkout develop
git pull
git checkout -b feature/f10-currency-selection
- Keep commits atomic and scoped.
- Use conventional commit messages.
After development:
git push -u origin feature/f10-currency-selection
- Open a PR to
develop, link the issue and request review.
🔃 2. Prepare a Release
git checkout develop
git pull
git checkout -b release/1.2.0
- Finalise version numbers (in
gatepress.php,readme.txt, etc.) - Complete CHANGELOG, fix edge bugs.
Merge into main:
git checkout main
git merge release/1.2.0
git tag -a v1.2.0 -m "Release v1.2.0: Adds PayPal integration + email fixes"
git push origin main --tags
Back-merge into develop:
git checkout develop
git merge main
🔥 3. Emergency Hotfix
git checkout main
git pull
git checkout -b hotfix/fix-stripe-error
- Commit a minimal patch
- Merge into
main, tag patch release (e.g.,v1.2.1) - Merge back into
developanysupport/*branches if needed
🛠 4. Support Branches
git checkout -b support/1.x v1.0.0
- Use for older versions still in use.
- Backport fixes or release
v1.0.1,v1.0.2from here.
✍️ Commit Message Convention (Conventional Commits)
| Prefix | Purpose |
|---|---|
feat: | New feature |
fix: | Bug fix |
docs: | Documentation updates |
style: | Refactoring without changing behaviour |
refactor: | Refactoring without changing behavior |
chore: | Tooling, build, dependencies |
Examples:
feat(payment): add currency selector for PayPal
fix(analytics): correct view counter reset logic
🪝 Git Hooks Path
Use a custom path for Git hooks:
.githooks/
├── pre-commit # Lint PHP, run PHPCS
├── commit-msg # Enforce Conventional Commits
├── pre-push # Run tests
Enable it:
git config core.hooksPath .githooks/
chmod +x .githooks/*
🔖 Version Tagging Guidelines
- Major (
v2.0.0): Breaking changes - Minor (
v1.1.0): New features - Patch (
v1.0.1): Fixes or hotfixes
Example:
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin --tags
🔒 Recommended Protections (GitHub/GitLab)
| Branch | Rule |
|---|---|
main | Protected: require PR + CI |
develop | Protected: require PR + tests |
release/* | Temporary branch, reviewed |
hotfix/* | Urgent, reviewed immediately |
🧩 Optional Automation & Tooling
| Tool | Purpose |
|---|---|
| Husky | Git hook runner |
| Lint-staged | Run linters only on staged files |
| PHPStan/Psalm | Static analysis |
| PHPCS | WordPress coding standards |
| Composer | Autoloading + dependency mgmt |
| GitHub Actions | CI/CD for lint, test, build |
📘 Example Release Checklist
- All features merged into
develop - Tests passed and reviewed
- Bump version.
- Generate
README.txt, changelog - Create and merge
release/*→main - Tag version (
git tag -a vX.Y.Z) - Merge
main→develop - Update documentation
- Upload the release.