ActivityPub Release Process

Quick reference for managing releases and changelogs for the WordPress ActivityPub plugin.

Quick Reference

Release Commands

npm run release              # Create major/minor release PR.

Version File Locations

When updating versions manually, change these files (these are the files bin/release.js touches):

• activitypub.php - Plugin header (Version: X.Y.Z) and the ACTIVITYPUB_PLUGIN_VERSION constant. Both must change.
• readme.txt - WordPress.org readme (Stable tag: X.Y.Z).
• includes/class-migration.php - Version references in the DB-migration version_compare() checks.
• CHANGELOG.md - Changelog file (auto-updated by release script).

Note: package.json has no version field and is not part of the release bump.

Comprehensive Release Guide

See Release Process for complete release workflow and detailed steps.

Release Workflow

Major/Minor Releases

Quick workflow:

# 1. Run release script from plugin root.
npm run release

# Script automatically:
# - Determines version from changelog entries.
# - Updates version numbers in all files.
# - Updates CHANGELOG.md.
# - Creates PR for review.

# 2. Review and merge the release PR.

# 3. Create GitHub release from trunk using the new tag.

See Release Process - Major/Minor for detailed steps.

Patch Releases

Quick workflow:

# 1. Create branch from the tag to patch.
git fetch --tags
git checkout -b tags/5.3.1 5.3.0  # Patch 5.3.0 -> 5.3.1

# 2. Cherry-pick merge commits from trunk (note -m 1 flag).
git cherry-pick -m 1 <commit-hash>

# 3. Update changelog and versions.
composer changelog:write

# Manually update versions in (see Version File Locations above):
# - activitypub.php (Version header AND ACTIVITYPUB_PLUGIN_VERSION constant)
# - readme.txt
# - includes/class-migration.php

# 4. Push branch and create GitHub release.
git push -u origin tags/5.3.1

Important: Use -m 1 flag when cherry-picking merge commits to select the mainline parent.

See Release Process - Patch Releases for detailed steps.

Changelog Management

How It Works

Changelogs are managed automatically through the PR workflow:

1. PR Template (.github/PULL_REQUEST_TEMPLATE.md):

   • Check "Automatically create a changelog entry" checkbox.
   • Select significance: Patch/Minor/Major.
   • Select type: Added/Fixed/Changed/Deprecated/Removed/Security.
   • Write message ending with punctuation!

2. GitHub Action (.github/workflows/changelog.yml):

   • Creates changelog file from PR description.
   • Validates proper punctuation.
   • Saves to .github/changelog/ directory.

3. Release Process:

   • npm run release aggregates all entries.
   • Updates CHANGELOG.md and readme.txt automatically.

Critical Requirements

Always end changelog messages with punctuation:

✅ Add support for custom post types.
✅ Fix signature verification bug.
❌ Add support for custom post types
❌ Fix signature verification bug

Write end-user friendly messages:

• Focus on user benefit, not implementation details.
• Avoid technical jargon where possible.
• Describe what users can now do, not how it works internally.

✅ Add pre-built block patterns for easy profile and sidebar setup.
✅ Fix follow button not appearing on author pages.
❌ Add register_patterns() method to class-blocks.php.
❌ Refactor User class to use Actors collection.

Pick the significance by what breaks for a real install:

• major bumps the plugin to the next whole version, so it has to be worth that: a user who keeps doing what they did before gets a materially worse or destructive result on a surface real installs depend on. Removing a public constant or breaking an opt-in experiment is not major. Raising the minimum WordPress or PHP version always is.
• Check that the break actually broke something before claiming it.

One entry per user-visible change. Split unrelated fixes into separate files, but several fixes to the same visible thing are one entry, however many issues they close.

No entry for a bug that never shipped. A fix for something introduced on the same unreleased branch is net zero for users.

Release PR bodies stay neutral. Use the release script's plain text; never enumerate or spotlight security fixes in a release PR or its notes.

Never mention AI tools or coding assistants in changelog messages.

See PR Workflow - Changelog for complete changelog requirements.

Version Numbering

Semantic versioning:

• Major (X.0.0) - Breaking changes.
• Minor (0.X.0) - New features, backward compatible.
• Patch (0.0.X) - Bug fixes only.

The release script determines version automatically from changelog entry significance levels.