Pr

ActivityPub 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 Review

Scope the review to what changed — don't review every PR:

• Skip for docs-only (*.md, docs/, README), tooling/config-only (.claude/, .agents/, workflow files), and trivial edits (typo, comment, whitespace). Push these straight to PR.
• Run the code-review agent only when the branch changes plugin code (PHP/JS/CSS logic). Address any critical issues before proceeding.

PR Creation

Every PR must:

• Assign @me
• Add Automattic/fediverse as reviewer
• Include changelog entry OR "Skip Changelog" label
• Pass CI checks
• Merge cleanly with trunk

# Create PR (includes required assignment/reviewer)
gh pr create --assignee @me --reviewer Automattic/fediverse

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 lint:js       # If JS changed
npm run lint:css      # If CSS changed
npm run env-test      # Run tests
npm run build         # If assets changed

See AGENTS.md for complete commands.

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 a [Pri] High (or [Pri] BLOCKER) 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 |

| Docs | Documentation updates |

| Code Quality | Refactoring, cleanup, etc. |

| Skip Changelog | No changelog needed |

| [Status] Needs review | Ready for review |

| [Status] In Progress | Still working |

| [Pri] High / [Pri] BLOCKER | Urgent / expedited |

Reference

See docs/pull-request.md for complete workflow details.