Skip to main content
This project uses a simplified Git Flow approach that keeps production code clean while allowing thorough testing in a staging environment.

​
Branch Overview

BranchPurposeDeploys To
trunkProduction-ready code (primary branch, source for all new branches)Production
stagingIntegration branch for testingStaging Environment
CRITICAL: staging is NEVER merged into trunk.The staging branch is only used for testing purposes. When changes are approved, the original working branch is merged directly into trunk. This keeps our production branch clean and ensures full traceability of individual changes.

​
Workflow Visualization

Notice that the arrow goes from your working branch directly to trunk, not from staging to trunk.

​
Branch Naming Conventions

Use descriptive branch names with the appropriate prefix:
TypePatternExampleUse Case
Featurefeature/short-descriptionfeature/user-authenticationNew functionality
Bug Fixbugfix/short-descriptionbugfix/login-validationNon-urgent fixes
Hotfixhotfix/short-descriptionhotfix/critical-security-patchUrgent production fixes

​
Branch Naming Guidelines

  • Use lowercase letters
  • Use hyphens (-) to separate words
  • Keep names short but descriptive
  • Include ticket/issue number if applicable: feature/123-user-auth
  • feature/block-editor-integration
  • bugfix/42-theme-color-override
  • hotfix/critical-xss-vulnerability
  • feature/rest-api-endpoints
  • bugfix/navigation-menu-alignment

​
Step-by-Step Workflow

The workflow is identical for all branch types. The only difference is the branch name prefix (feature/, bugfix/, or hotfix/).
1

Create your branch from trunk

Always create new branches from the latest trunk:
git checkout trunk
git pull origin trunk
git checkout -b <type>/your-branch-name
Replace <type> with feature, bugfix, or hotfix depending on your work.
2

Make your changes

Write your code and commit frequently:
# Make changes to your code
git add .
git commit -m "feat: add user login functionality"
See commit message format for guidelines.
3

Keep your branch updated

Regularly sync with the latest trunk changes:
git fetch origin
git rebase origin/trunk
Using rebase instead of merge keeps your commit history clean and linear.
4

Merge directly into staging (No PR required)

Deploy to staging for testing:
git checkout staging
git pull origin staging
git merge <type>/your-branch-name
git push origin staging
This deploys your changes to the Staging Environment for QA testing.
No Pull Request is required for merging to staging. This is a direct merge.
5

Wait for QA approval

Your changes will be tested in the staging environment. The QA team will review:
  • Functionality works as expected
  • No regressions introduced
  • Meets acceptance criteria
  • Performance is acceptable
6

Open a Pull Request to trunk

After QA approval, create a Pull Request from your working branch directly to trunk:
  • Source: Your feature/, bugfix/, or hotfix/ branch
  • Target: trunk
  • NOT from staging
Once merged, your changes deploy to Production.

​
Visual Flow Diagram

<type>/your-branch-name
         │
         ├────► staging (direct merge, no PR)
         │           │
         │           ▼
         │      Staging Environment
         │           │
         │       QA Approval
         │           │
         │           ▼
         └────► trunk (Pull Request required)
                     │
                     ▼
              Production Environment

​
Pull Request Process

Pull Requests are only required when merging to trunk. You can merge directly to staging without a PR.

​
Before Submitting a PR to Trunk

Ensure your checklist is complete:
  • Code has been tested in the staging environment
  • QA has approved the changes
  • Code follows project style guidelines
  • All tests pass locally
  • Branch is up to date with trunk
  • Commit messages are clear and descriptive
  • Documentation is updated (if applicable)

​
PR Requirements

1

Write a clear title

Use a descriptive title that summarizes the change:
  • “Add REST API endpoints for custom post types”
  • “Fix navigation menu alignment on mobile devices”
  • “Update block editor integration for WordPress 6.9”
2

Provide detailed description

Explain:
  • What changes were made
  • Why they were necessary
  • How to test the changes
  • Any breaking changes or migration steps
3

Request reviewers

Request at least one reviewer who is familiar with the area of code you’re changing.
4

Add appropriate labels

Use labels to categorize your PR:
  • feature for new functionality
  • bugfix for fixes
  • documentation for docs changes

​
Merge Strategy

Target BranchMethodPR Required
stagingDirect merge❌ No
trunkMerge commit✅ Yes

​
What NOT To Do

Avoid these common mistakes:
ActionWhy It’s Wrong
Merge staging into trunkstaging may contain untested or unapproved code
Create branches from stagingstaging is not the source of truth
Skip testing in stagingChanges must be tested before production
Merge to trunk before QA approvalUntested code could reach production
Open a PR to stagingDirect merges are preferred for staging

​
Quick Reference

# Start any new work (always from trunk)
git checkout trunk && git pull
git checkout -b <type>/description   # feature/, bugfix/, or hotfix/

# Make your changes and commit
git add .
git commit -m "feat: description of change"

# Update your branch with latest trunk
git fetch origin
git rebase origin/trunk

# Merge to staging for testing (no PR needed)
git checkout staging
git pull origin staging
git merge <type>/description
git push origin staging

# After QA approval, create PR from your branch to trunk
# (Do this via GitHub/GitLab UI)

​
Branch Rules Summary

RuleDescription
Create fromAlways create branches from trunk
Staging mergeDirect merge (no PR required)
Trunk mergePull Request required
NeverNever merge staging into trunk
NeverNever create branches from staging

​
Deployment

The project uses GitHub Actions to automatically deploy vendor folders:
  • Workflow file: .github/workflows/deploy-vendors.yml
  • Triggers on every push to trunk or staging
  • Can be triggered manually via GitHub Actions UI
BranchEnvironment
trunkproduction
stagingstaging
The workflow:
  1. Runs composer install --no-dev for each plugin/theme
  2. Uploads the vendor/ folder to the appropriate environment
  3. Uses GitHub Environments to separate production and staging credentials
  4. Deploys via SFTP to WordPress.com hosting

​
Questions?

If you have questions about the workflow:

Open an Issue

Open an issue with the question label for workflow questions.

Contact Maintainers

Reach out to the maintainers for clarification.

Build docs developers (and LLMs) love

Get started for freeTalk to us