Skip to content

RELEASE.md

Latest commit

 

History

History
199 lines (142 loc) · 5.21 KB

RELEASE.md

File metadata and controls

199 lines (142 loc) · 5.21 KB

Release Process

This document outlines the process for releasing new versions of Setlist Player.

Versioning Strategy

This plugin follows the wordpress-develop versioning practice:

  1. After releasing version X.Y.Z, immediately bump to the next anticipated version (X.Y+1.0)
  2. All subsequent commits are part of the next release
  3. When ready to release, tag and release, then bump again

Example Flow

Prepare 1.0.0 → Commit → Tag v1.0.0 → Push → Create GitHub Release → Bump to 1.1.0 → Development

When ready for 1.1.0, repeat the process.

This project follows Semantic Versioning (MAJOR.MINOR.PATCH).

Distribution Model

  • Development: All development happens in GitHub
  • GitHub Releases: Tagged releases distributed as complete zip files
  • WordPress.org SVN: Only final tagged releases are pushed to SVN (no development versions)
    • SVN trunk contains the latest release
    • SVN tags contain specific releases
    • All version numbers match within each release

Version Locations

Version numbers must be updated in these files:

  1. setlist-player.php (main plugin file)

    • Version: header (line ~10)
    • SETLIST_PLAYER_VERSION constant (line ~24)

  2. readme.txt (WordPress.org readme)

    • Stable tag: field (line ~8)

  3. package.json

    • version field (line ~2)

Note that the versions indicated in block.json files are specific to their blocks, and not the plugin release version.

Pre-Release Checklist

Before creating a release, ensure:

  • All tests pass (npm test)
  • Code is linted and formatted (npm run lint)
  • CHANGELOG section in readme.txt is updated with changes
  • Version numbers are correct across all files (see "Version Locations" above)
  • readme.txt "Tested up to" field reflects latest WordPress version tested
  • Documentation is up to date (README.md, CONTRIBUTING.md)
  • Build is clean (npm run build)

Release Steps

1. Prepare the Release

# Ensure you're on trunk and up to date
git checkout trunk
git pull origin trunk

# Run full test suite
npm test

# Ensure build is clean
npm run build

# Run linting
npm run lint

2. Update Changelog

Edit readme.txt and add release notes under the == Changelog == section:

== Changelog ==

= 1.0.0 =
* Feature: Add new keyboard shortcut for audio-only mode
* Enhancement: Improve playlist loading performance
* Fix: Resolve issue with speed control not persisting

3. Update Version Numbers

Update version in all locations listed above. For example, when releasing 1.0.0:

setlist-player.php:

* Version:           1.0.0
define( 'SETLIST_PLAYER_VERSION', '1.0.0' );

readme.txt:

Stable tag: 1.0.0

package.json:

"version": "1.0.0"

4. Commit and Tag

# Commit version bump
git add setlist-player.php readme.txt package.json
git commit -m "Release version 1.0.0"

# Create annotated tag (use -a flag for annotated tag, not lightweight)
git tag -a v1.0.0 -m "Version 1.0.0"

# Push commit and tag together
git push --follow-tags origin trunk

Note on Tags:

  • Always use annotated tags (-a flag) for releases
  • Use git push --follow-tags to push commits and their associated annotated tags together
  • Alternatively, push tags explicitly with git push origin <tagname>

5. Create GitHub Release

  1. Go to the Releases page
  2. Click "Draft a new release"
  3. Select the tag you just created (v1.0.0)
  4. Title: "Version 1.0.0"
  5. Description: Copy the changelog from readme.txt
  6. Attach the distribution zip (generated via npm run plugin-zip)
  7. Publish release

6. Deploy to WordPress.org

(For future use when plugin is approved)

WordPress.org deployment is handled by pushing tagged releases from GitHub to WordPress.org SVN. Consider using 10up/action-wordpress-plugin-deploy GitHub Action to automate this process.

7. Post-Release Version Bump

Immediately after releasing, bump to the next version. For example, after releasing 1.0.0:

setlist-player.php:

* Version:           1.1.0
define( 'SETLIST_PLAYER_VERSION', '1.1.0' );

readme.txt:

Stable tag: 1.1.0

package.json:

"version": "1.1.0"

Commit the bump:

git add setlist-player.php readme.txt package.json
git commit -m "Bump version to 1.1.0"
git push origin trunk

Common Issues

Version Mismatch

If you notice version numbers are out of sync:

  • All three files (setlist-player.php, readme.txt, package.json) should have matching version numbers
  • Each released zip is self-contained with all versions matching
  • Trunk can have unreleased version numbers since trunk isn't distributed

Forgotten Post-Release Bump

If you forget to bump the version after a release:

  • Do it as soon as you notice
  • This ensures all new commits are clearly marked as part of the next release

Wrong Version Number

If you realize you tagged the wrong version:

  • Delete the local tag: git tag -d v1.0.0
  • Delete the remote tag: git push origin :refs/tags/v1.0.0
  • Delete the GitHub release
  • Start over with the correct version