Automattic/pr

ATmosphere PR Workflow

Branch Naming

| Prefix | Use | |--------|-----| | add/{feature} | New features | | update/{feature} | Iterating on existing features | | fix/{bug} | Bug fixes | | try/{idea} | Experimental ideas |

Reserved: release/{X.Y.Z} (releases only), trunk (main branch).

Pre-PR Checks

Before creating a PR, you MUST complete these steps in order:

1. Run PHPCS and PHPUnit

composer lint         # MUST pass with zero errors
npm run env-test      # MUST pass all tests

Fix any failures before proceeding. Do not create a PR with failing checks.

2. Changelog entry

Every PR MUST either:

• Include a changelog file in .github/changelog/ (see Changelog below), OR
• Add the Skip Changelog label to the PR

Add the changelog entry as part of your initial commit, not after the PR is created. If neither changelog nor label is present, stop and ask the user which they prefer before creating the PR.

3. Code review

Delegate to the code-review agent to review all changes on the branch. Address any critical issues before proceeding.

PR Creation

Every PR must:

• Assign @me
• Include changelog entry OR "Skip Changelog" label
• Pass PHPCS and PHPUnit (verified above)
• Merge cleanly with trunk

# Create PR (includes required assignment)
gh pr create --assignee @me

Use the exact template from .github/PULL_REQUEST_TEMPLATE.md — do not create custom formatting.

Changelog

Write changelog messages for end users, not developers. Users read these in the WordPress plugin update screen. Avoid internal jargon (OOM, batching, N+1), class names, or method names. Describe what the user experiences or what changed from their perspective.

✅ Fix automatic cleanup of old activities failing silently on sites with many items.
✅ Add a Site Health check that warns when plugins are causing too many federation updates.
❌ Fix collection purge methods to batch deletions and enforce a hard item cap.
❌ Add Site Health test to detect excessive outbox activity rates.

End all changelog messages with punctuation.

Add manually if forgotten:

composer changelog:add
git add . && git commit -m "Add changelog entry" && git push

See release for complete changelog details.

Workflow

Create Branch

git checkout trunk && git pull origin trunk
git checkout -b fix/notification-issue

Pre-Push Checks

composer lint         # PHP standards (composer lint:fix to auto-fix)
npm run env-test      # Run tests

Keep Branch Updated

git fetch origin
git rebase origin/trunk
# Resolve conflicts if any
git push --force-with-lease

Special Cases

Hotfixes: Branch fix/critical-issue, minimal changes, add "Hotfix" label, request expedited review.

Experimental: Use try/ prefix, mark as draft, get early feedback, convert to proper branch type once confirmed.

Multi-PR features: Create tracking issue, link all PRs, use consistent naming (add/feature-part-1, etc.), merge in order.

Labels

| Label | Use | |-------|-----| | Bug | Bug fixes | | Enhancement | New features | | Documentation | Doc updates | | Code Quality | Refactoring, cleanup, etc. | | Skip Changelog | No changelog needed | | Needs Review | Ready for review | | In Progress | Still working | | Hotfix | Urgent fix |