Git Workflow

Git workflow for WooCommerce development including branching, commits, pull requests, and changelog requirements

WooCommerce follows a structured Git workflow to maintain code quality and enable efficient collaboration. This guide covers branching strategies, commit conventions, pull request requirements, and changelog management.

Repository Structure

WooCommerce is organized as a monorepo containing multiple packages and plugins:

woocommerce/
├── plugins/
│   ├── woocommerce/              # Core plugin
│   └── woocommerce-beta-tester/  # Beta tester plugin
├── packages/
│   ├── js/                        # JavaScript packages
│   └── php/                       # PHP packages
└── tools/                         # Development tools

Changes to any package require a changelog entry for that specific package before creating a PR.

Branching Strategy

WooCommerce uses a trunk-based development workflow:

Branch Types

trunk

• Main development branch
• All PRs target trunk by default
• Always in a releasable state
• Automatically deployed to staging

Feature Branches

• Created from trunk
• Named descriptively: add/order-filtering
• Merged back to trunk via PR
• Deleted after merge

Release Branches

• Created from trunk for releases
• Named release/X.Y
• Receive only critical fixes
• Managed by core team

Hotfix Branches

• Created from release branch
• Named fix/critical-bug
• Merged to release and trunk
• For critical production issues only

Creating a Feature Branch

1. Fork the Repository

   Fork WooCommerce to your GitHub account via the repository page.

2. Clone Your Fork

   git clone https://github.com/YOUR-USERNAME/woocommerce.git
   cd woocommerce
   
3. Add Upstream Remote

   git remote add upstream https://github.com/woocommerce/woocommerce.git
   git fetch upstream
   
4. Create Feature Branch

   # Update your local trunk
   git checkout trunk
   git pull upstream trunk
   
   # Create feature branch
   git checkout -b add/order-export-feature
   

Branch Naming Conventions

Use descriptive prefixes for branch names:

• add/ - New features
• update/ - Enhancements to existing features
• fix/ - Bug fixes
• dev/ - Development/infrastructure changes
• tweak/ - Minor adjustments

# ✅ Good branch names
add/order-export-csv
fix/checkout-validation-error
update/product-search-performance
dev/upgrade-phpunit-version

# ❌ Bad branch names
my-changes
test
fix-bug

Commit Guidelines

Write clear, meaningful commit messages that explain why changes were made, not just what changed.

Commit Message Format

Short summary (50 chars or less)

More detailed explanation if necessary. Wrap at 72 characters.
Explain the problem this commit solves and why this approach
was chosen over alternatives.

Closes #123

Writing Good Commit Messages

Do

# ✅ Good commits
git commit -m "Add CSV export for orders

Implements CSV export functionality requested in #456.
Uses league/csv for proper encoding and performance.

Closes #456"

git commit -m "Fix checkout validation for empty fields

Validates all required fields before form submission
to prevent incomplete orders. Adds client-side validation
for better UX.

Fixes #789"

Don't

# ❌ Bad commits
git commit -m "fix bug"
git commit -m "updates"
git commit -m "WIP"
git commit -m "changes"

Commit Message Best Practices

• Use present tense (“Add feature” not “Added feature”)
• Capitalize first letter of summary
• No period at end of summary line
• Reference issue numbers with Closes #123 or Fixes #456
• Keep summary under 50 characters
• Wrap body at 72 characters
• Explain why, not just what

Linking to Issues

Reference issues and PRs in commit messages:

# Close an issue
git commit -m "Fix order total calculation

Closes #1234"

# Reference without closing
git commit -m "Improve order query performance

Related to #2345"

# Reference bug-introducing PR
git commit -m "Fix regression in checkout flow

Bug introduced in PR #3456"

Changelog Management

NEVER create a PR without changelog entries. Each affected package requires its own changelog entry.

Creating Changelog Entries

Before creating a PR, add changelog entries for each modified package:

# For WooCommerce Core
pnpm --filter=@woocommerce/plugin-woocommerce changelog add

# For other packages
pnpm --filter=@woocommerce/components changelog add
pnpm --filter=@woocommerce/data changelog add

1. Run Changelog Command

   cd plugins/woocommerce
   pnpm changelog add
   
2. Select Change Significance

   ? Select the significance of this change:
     patch   - Bug fixes, minor changes
     minor   - New features, non-breaking changes
     major   - Breaking changes
   
3. Select Change Type

   ? Select the type of change:
     Fix           - Fixes an existing bug
     Add           - Adds new functionality  
     Update        - Updates existing functionality
     Dev           - Development related task
     Tweak         - Minor adjustment to codebase
     Performance   - Performance improvements
     Enhancement   - Improvement to existing functionality
   
4. Write Changelog Message

   ? Enter a short description of the change:
   Add CSV export functionality for orders
   
5. Commit Changelog File

   git add changelog/
   git commit -m "Add changelog entry"
   

Changelog File Format

Changelog entries are created as YAML files:

changelog/fix-checkout-validation

significance: patch
type: fix
message: Fix checkout validation for required fields

Pull Request Workflow

Before Creating a PR

1. Ensure Tests Pass

   # Run relevant tests
   pnpm test:php:env
   pnpm test:e2e
   
2. Run Linting

   # Lint changed files
   pnpm --filter=@woocommerce/plugin-woocommerce lint:php:changes
   pnpm --filter=@woocommerce/plugin-woocommerce lint:lang:js
   
3. Run PHPStan

   # Analyze modified PHP files
   cd plugins/woocommerce
   composer exec -- phpstan analyse src/path/to/File.php --memory-limit=2G
   
4. Create Changelog Entries

   # Add changelog for each affected package
   pnpm --filter=@woocommerce/plugin-woocommerce changelog add
   
5. Push Changes

   git push origin add/your-feature-branch
   

Creating the Pull Request

1. Open GitHub PR

   Navigate to your fork on GitHub and click “Compare & pull request”

2. Fill PR Template

   Use the provided template from .github/PULL_REQUEST_TEMPLATE.md:

   ### Changes proposed in this Pull Request:
   
   This PR adds CSV export functionality for orders, allowing
   merchants to export order data for external processing.
   
   Closes #456
   
   ### How to test the changes in this Pull Request:
   
   1. Navigate to WooCommerce > Orders
   2. Select multiple orders using checkboxes
   3. Choose "Export to CSV" from bulk actions
   4. Click "Apply"
   5. Verify CSV downloads with correct data
   
   ### Screenshots or screen recordings:
   
   [Include screenshots if UI changed]
   
3. Set Milestone

   Check the box to auto-assign milestone:

   - [x] Automatically assign milestone for next WooCommerce version
   
4. Add Labels

   Add appropriate labels:

   • type: enhancement, type: fix, etc.
   • focus: area-name for specific features

Pull Request Template Sections

Submission Review

### Submission Review Guidelines:

- [x] I have followed the WooCommerce Contributing Guidelines
- [x] I have followed WordPress Coding Standards  
- [x] I have checked for other open PRs for same change
- [x] I have reviewed my code for security best practices

Changes Description

### Changes proposed in this Pull Request:

<!-- Describe what changed and why -->

Closes #123

<!-- For bug fixes -->
Bug introduced in PR #456

Testing Instructions

### How to test the changes in this Pull Request:

Using the WooCommerce Testing Instructions Guide:

1. Step one with specific details
2. Step two with expected outcome
3. Step three with verification steps

Changelog Entry

### Changelog entry

- [x] Automatically create changelog from details below

#### Significance
- [x] Patch

#### Type  
- [x] Add - Adds functionality

#### Message
Add CSV export functionality for orders

PR Review Process

1. Automated Checks

   • Linting (PHP, JavaScript)
   • PHPUnit tests
   • E2E tests
   • API tests
   • PHPStan analysis
2. Code Review

   • Core team reviews code
   • Requests changes if needed
   • Approves when ready
3. Address Feedback

   # Make requested changes
   git add .
   git commit -m "Address review feedback"
   git push origin add/your-feature-branch
   
4. Merge

   • PR is merged to trunk by maintainer
   • Branch is automatically deleted

Advanced Git Workflows

Keeping Your Branch Updated

# Fetch latest changes from upstream
git fetch upstream

# Rebase your branch on latest trunk
git checkout add/your-feature
git rebase upstream/trunk

# Force push if already pushed (use with caution)
git push origin add/your-feature --force-with-lease

Only use --force-with-lease on your own feature branches, never on shared branches or trunk.

Squashing Commits

Squash multiple commits before merging:

# Interactive rebase for last 3 commits
git rebase -i HEAD~3

# In the editor, change 'pick' to 'squash' for commits to combine
pick abc123 First commit
squash def456 Second commit  
squash ghi789 Third commit

# Edit combined commit message
# Force push to update PR
git push origin add/your-feature --force-with-lease

Cherry-Picking Changes

Apply specific commits to another branch:

# Using the monorepo cherry-pick tool
pnpm cherry-pick <commit-hash> <target-branch>

# Manual cherry-pick
git checkout release/9.0
git cherry-pick abc123
git push upstream release/9.0

Common Git Issues

Merge conflicts

# Update trunk
git fetch upstream
git checkout trunk
git merge upstream/trunk

# Rebase feature branch
git checkout add/your-feature
git rebase trunk

# Resolve conflicts in your editor
# After resolving:
git add .
git rebase --continue

Wrong branch committed to

# If committed to trunk instead of feature branch
git checkout trunk
git reset --soft HEAD~1  # Undo commit, keep changes
git stash                # Stash changes
git checkout -b add/new-feature  # Create feature branch
git stash pop           # Apply changes
git commit              # Commit to feature branch

Forgot to create changelog

# Create changelog entry
pnpm --filter=@woocommerce/plugin-woocommerce changelog add

# Amend last commit to include changelog
git add changelog/
git commit --amend --no-edit

# Force push to update PR
git push origin add/your-feature --force-with-lease

Need to update PR after push

# Make additional changes
git add .
git commit -m "Address review feedback"
git push origin add/your-feature

# PR will automatically update

Git Best Practices

Do’s

• ✅ Keep commits focused and atomic
• ✅ Write descriptive commit messages
• ✅ Reference issues in commits and PRs
• ✅ Create changelog entries before PRs
• ✅ Rebase on trunk regularly
• ✅ Test before pushing
• ✅ Use meaningful branch names

Don’ts

• ❌ Commit directly to trunk
• ❌ Force push to shared branches
• ❌ Create PRs without changelog entries
• ❌ Commit without testing
• ❌ Use vague commit messages
• ❌ Include unrelated changes in commits
• ❌ Commit sensitive data or credentials

GitHub CLI (gh)

Use GitHub CLI for efficient PR management:

# Install gh
brew install gh  # macOS

# Authenticate
gh auth login

# Create PR from command line
gh pr create --title "Add order export feature" \
  --body "Implements CSV export for orders. Closes #456"

# Check PR status
gh pr status

# View PR checks
gh pr checks

# Checkout PR locally
gh pr checkout 123

# View PR diff
gh pr diff 123

Pre-commit Hooks

WooCommerce uses Husky for pre-commit hooks that automatically:

• Run PHP syntax check (php -l)
• Run PHP_CodeSniffer on staged files
• Run ESLint on staged JavaScript files
• Fix auto-fixable issues

.husky/pre-commit

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

pnpm exec lint-staged

Pre-commit hooks help catch issues before they reach CI, saving time and ensuring code quality.

Summary Checklist

Before creating a PR, ensure:

• Created feature branch from latest trunk
• Made focused, atomic commits with good messages
• Added changelog entries for all affected packages
• All tests pass locally
• Linting passes (PHP and JavaScript)
• PHPStan analysis passes
• PR description follows template
• Testing instructions are clear
• Referenced related issues
• Added screenshots for UI changes
• Set appropriate milestone
• Added relevant labels

Next Steps

Coding Standards

Review coding standards and linting requirements

Testing

Learn about testing requirements and commands