activitypub-release

Original source / Raw SKILL.md

---
name: activitypub-release
description: Version management and release processes using Jetpack Changelogger. Use when creating releases, managing changelogs, bumping versions, or preparing patch releases.
---

# ActivityPub Release Process

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

## Quick Reference

### Release Commands
```bash
npm run release              # Create major/minor release PR.
```

### Version File Locations
When updating versions manually, change these files:
- `activitypub.php` - Plugin header (`Version: X.Y.Z`).
- `readme.txt` - WordPress.org readme (`Stable tag: X.Y.Z`).
- `package.json` - npm version (`"version": "X.Y.Z"`).
- `CHANGELOG.md` - Changelog file (auto-updated by release script).

## Comprehensive Release Guide

See [Release Process](../../../docs/release-process.md) for complete release workflow and detailed steps.

## Release Workflow

### Major/Minor Releases

**Quick workflow:**
```bash
# 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](../../../docs/release-process.md) for detailed steps.

### Patch Releases

**Quick workflow:**
```bash
# 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:
# - activitypub.php
# - readme.txt
# - package.json

# 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](../../../docs/release-process.md#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
```

**Never mention AI tools or coding assistants in changelog messages.**

See [PR Workflow - Changelog](../activitypub-pr-workflow/SKILL.md#changelog-management) 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.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../../../docs/release-process.md

```markdown
# Release Process

This document outlines the process for creating new releases of the WordPress ActivityPub plugin. The process differs slightly between major/minor releases and patch releases.

## Major and Minor Releases

Major and minor releases follow the same release process. These releases are created from the `trunk` branch.

### Steps

1. **Generate Version Bump PR**
   - Use the release script to automatically generate a version bump pull request:
     ```bash
     # From the plugin root directory
     npm run release
     ```
   - The script will:
     - Determine the new version number based on the unreleased changelog entries.
     - Update version numbers in relevant files
     - Update `CHANGELOG.md` and `readme.txt` with the changelog entries
     - Create a new branch
     - Commit changes
     - Push to GitHub
     - Create a pull request

2. **Review and Merge**
   - Review the generated PR to ensure all version numbers and changelog entries are correct.
   - Once approved, merge the PR into `trunk`.

3. **Create Release**
   - On GitHub, navigate to the main page of the repository.
   - To the right of the list of files, click **Releases**.
   - At the top of the page, click **Draft a new release**. 
   - To choose a tag for the release, select the **Choose a tag** dropdown menu.
     - Type the version number for your release, then click **Create new tag**.
   - Select the **Target** dropdown menu, then click `trunk`.
   - Select the **Previous tag** dropdown menu, then click the tag that identifies the previous release.
   - Above the description field, click **Generate release notes**.
   - If you're ready to publicize your release, click **Publish release**.
   ![Major/minor release UI](images/release-ui-major.png)

## Patch Releases

Patch releases require a more manual process as they need to be created from the previous release branch.

### Steps

1. **Restore Release Branch**
   - Locate the most recent release branch (for `5.3.0` it was `release/5.3.0`, created via [#1371](https://github.com/Automattic/wordpress-activitypub/pull/1371)).
   - Click "Restore branch" to recreate it.
   - Locally, checkout that release branch you just restored: `git fetch origin release/5.3.0 && git checkout release/5.3.0`

2. **Cherry-pick Changes into the release branch**
   - Identify merge commits from `trunk` that need to be included. You can find them at the bottom of each PR:

<img width="904" alt="image" src="https://github.com/user-attachments/assets/4c49c5bd-928c-44d2-b64b-39454baa8d9d" />

   - Cherry-pick each merge commit into this branch:
     ```bash
     # Checkout the release branch.
     git checkout release/5.3.0

     # Cherry-pick a merge commit.
     git cherry-pick -m 1 <commit-hash>
     ```
     > Note: The `-m 1` flag is required when cherry-picking merge commits. Merge commits have two parent commits - the first parent (`-m 1`) is the target branch of the original merge (usually the main branch), and the second parent (`-m 2`) is the source branch that was being merged. We use `-m 1` to tell Git to use the changes as they appeared in the main branch.

   - Resolve merge conflicts that may come up as you cherry-pick commits.

3. **Update changelog and version numbers**
   - Run `composer changelog:write`. It will update `CHANGELOG.md` with the changelog entries you cherry-picked, and will give you a version number for that release.
   - Edit `readme.txt` to paste the changelog entries from `CHANGELOG.md` into the `== Changelog ==` section.
   - The release script doesn't support releasing patch versions, so you'll need to manually update version numbers in the different files (`activitypub.php`, `readme.txt`, and files that may have been changed to introduce an `unreleased` text).

4. **Review and push your changes**
   - Review your changes locally, and `git push` to push your changes to the remote.

5. **Create Release**
   - On GitHub, navigate to the main page of the repository.
   - To the right of the list of files, click **Releases**.
   - At the top of the page, click **Draft a new release**. 
   - To choose a tag for the release, select the **Choose a tag** dropdown menu.
     - Type the version number for your release, then click **Create new tag**.
   - Select the **Target** dropdown menu, then click the branch that contains the patches you want to release.
   - Select the **Previous tag** dropdown menu, then click the tag that identifies the previous release.
   - Above the description field, click **Generate release notes**.
   - If you're ready to publicize your release, click **Publish release**.
   ![Patch release UI](images/release-ui-patch.png)

```