ATmosphere Release Process

Quick-reference for cutting a release. Full reference: docs/release-process.md.

Major / Minor Release

npm run release

The script (bin/release.js) handles everything: changelog roll-up, version bump in atmosphere.php / readme.txt / package.json, readme.txt changelog mirror, unreleased marker replacement across *.php, optional Upgrade Notice prompt, then commits / pushes / opens a Release X.Y.Z PR.

Prerequisites: clean working tree, on trunk (or it'll switch you), gh CLI authenticated, at least one entry in .github/changelog/.

After the PR merges: draft the GitHub Release against trunk with the new tag.

Patch Release

The script doesn't handle these — patches are cherry-picked manually onto the previous release branch:

git fetch origin release/X.Y.0
git checkout release/X.Y.0
git cherry-pick -m 1 <merge-commit-hash>
composer changelog:write
# Update readme.txt changelog block, bump versions in atmosphere.php / readme.txt / package.json,
# replace any remaining `unreleased` markers.
git push origin release/X.Y.0
# Open PR against release/X.Y.0; draft GitHub Release with the new tag targeting that branch.

Full step-by-step: docs/release-process.md → Patch Releases.

Changelog Entries

composer changelog:add       # Add one entry to .github/changelog/.
composer changelog:write     # Roll up entries into CHANGELOG.md (script does this for you).

Required: end the message with punctuation, write for end users (no class names, no AI/assistant references).

✅ Fix posts not appearing on Bluesky when published via Quick Edit.
✅ Add option to disable standard.site document records.
❌ Refactor Publisher class to handle edge case in applyWrites batch.
❌ Fix TID collision in transformer output.

Marking Unreleased Code

When adding a new public hook, deprecation, or _doing_it_wrong call, use the literal unreleased. The release script rewrites it:

/**
 * @since unreleased
 */

\_deprecated_function( __FUNCTION__, 'unreleased', 'new_function' );
\apply_filters_deprecated( 'atmosphere_old_filter', array( $value ), 'unreleased', 'atmosphere_new_filter' );
\_doing_it_wrong( __METHOD__, \__( 'Use new_method().', 'atmosphere' ), 'unreleased' );

Semver Bumps

Bump	When
Major (X.0.0)	Breaking public-hook signature changes, removed features, schema requires migration.
Minor (0.X.0)	New features, new public hooks, backward-compatible behaviour changes.
Patch (0.0.X)	Bug fixes only — no public hook changes.

If any pending entry is marked Significance: major, the changelogger bumps to a new major version. Otherwise minor if any is minor, else patch.

When to Read the Full Docs

Read docs/release-process.md when you need:

• The full step-by-step for major / minor releases.
• The patch-release cherry-pick workflow with conflict-resolution tips.
• Version file locations for manual bumps (patch path).
• Manual steps the script doesn't handle (distributable ZIP, wp.org SVN asset upload, GitHub Release tagging).
• Troubleshooting (branch-already-exists, empty changelog section, mirrored readme.txt looks wrong).

Related Skills

• pr — branching, pre-PR checklist, changelog entry format.
• dev — wp-env, testing the release branch locally.