Creating Releases

(Stale) Creating a changelog

Use these icons to categorize changelog line items, as done by AMP core:

• ✨ New feature
• 🐛 Bug fix
• 🔥 P0 fix
• ✅ Tests
• ❄️ Flaky tests
• 🚀 Performance improvements
• 🖍 CSS / Styling
• ♿ Accessibility
• 🌐 Internationalization
• 📖 Documentation
• 🏗 Infrastructure / Tooling / Builds / CI
• ⏪ Reverting a previous change
• ♻️ Refactoring
• 🚮 Deleting code

Creating a prerelease

1. Create changelog draft on Wiki page.
2. Check out the branch intended for release (develop for major, x.y for minor) and pull latest commits.
3. Bump plugin versions in amp.php (2×: the metadata block in the header and also the AMP__VERSION constant). Commit and push.
4. Wait for the GitHub actions to create new build ZIPs for the branch. Alternatively, you may create the build ZIP yourself: npm install && composer selfupdate --2 && composer install --prefer-source --no-interaction && npm run build:prod.
5. Install the amp.zip onto a normal WordPress install running a stable release build; do smoke test to ensure it works.
6. Draft new release on GitHub targeting the required branch (develop for major, x.y for minor).
   1. Use the new plugin version as the tag (e.g. 1.2-beta3 or 1.2.1-RC1)
   2. Use new version as the title, followed by some highlight tagline of the release.
   3. Attach the amp.zip build to the release.
   4. Add changelog entry to the release, link to compare view comparing previous release, and link to milestone.
   5. Make sure “Pre-release” is checked.
7. Verify the release branch has the pushed commit! Double check GHA.
8. Publish GitHub release.
9. (Deprecated?) Create built release tag (from the just-created build directory):
   1. Do git fetch origin --tags && ./bin/tag-built.sh
   2. Add link from release notes.
10. Make announcements on Twitter and the #amp-wp channel on AMP Slack, linking to release post or GitHub release.
11. Bump version in release branch, e.g. …-alpha to …-beta1 and …-beta2 to …-RC1
12. If prerelease is RC, create the release branch now. Bump develop to alpha.
13. Make any necessary changes to Development Builds Wiki page.

Creating a stable release (new)

1. Copy these instructions into a Google Doc and share with those doing the release. Convert bullets to checkboxes.
2. Create changelog draft on Wiki page. Add changelog entry for each issue/PR which isn't a dependency update. Add Changelogged label when added. Keep track of contributors.
3. Update readme including the description, contributors, and screenshots (as needed).
4. Check out the branch intended for release (develop) and pull latest commits.
5. Update metadata:
   1. Bump plugin versions in amp.php (×2: the metadata block in the header and also the AMP__VERSION constant). Verify via npx grunt shell:verify_matching_versions. Ensure patch version number is supplied for major releases, so 1.2-RC1 should bump to 1.2.0.
   2. Ensure "Tested Up To" is updated to current WordPress version.
   3. Re-run wp amp docs generate (also npx wp-env run cli wp amp docs generate), verify changes, and commit any docs updates. (This is not working with wp-env.)
   4. Commit and push.
6. Verify the release branch has the pushed commit! Double check GHA.
7. Download the ZIP from the GHA build and checksum:

   wget -O amp.zip.sha256 https://storage.googleapis.com/ampwp_github_artifacts/refs/heads/develop/prod/amp.zip.sha256; 
   wget -O amp.zip https://storage.googleapis.com/ampwp_github_artifacts/refs/heads/develop/prod/amp.zip; 
   rm -r build; 
   mkdir build; 
   cd build; 
   unzip ../amp.zip; 
   cd ..;

8. Draft new release on GitHub targeting the required branch (develop for major, x.y for minor):
   1. Use the new plugin version as the tag (e.g. 1.2.0 or 1.2.1)
   2. Attach the amp.zip build to the release.
   3. Attach sha256 checksum as amp.zip.sha256.
   4. Add changelog entry to the release and link to compare view comparing previous release.
9. Install the amp.zip onto a normal WordPress install running a stable release build; do smoke test to ensure it works.
10. Optionally do sanity check by comparing the build directory with the previously-deployed plugin on WordPress.org for example: svn export https://plugins.svn.wordpress.org/amp/trunk /tmp/amp-trunk; diff -r /tmp/amp-trunk/ ./build/ (instead of straight diff, it's best to use a GUI like idea diff, phpstorm diff, opendiff, or meld).
11. Run npm run deploy to commit the plugin to WordPress.org.
12. Open confirmation email.
13. Click view changes and compare SVN diff with previous release.
14. Publish GitHub release.
15. Press to Confirm the release on WordPress.org.
16. Verify the release is available on WordPress.org; try installing it on a WordPress install and confirm it works.
17. Create built release tag (from the just-created build directory):
    1. Do git fetch origin --tags && ./bin/tag-built.sh
    2. Add link from release notes.
18. Bump version in release branch. For example, bump to 1.3.0-alpha on develop.
19. Update docs on amp-wp.org, where $version is the version that was just released: terminus remote:wp wordpress-amp.live -- docs generate --version=$version | cat -
20. Close the GitHub milestone.
21. Archive cards in project in Passed QA column.
22. Make any necessary changes to Development Builds Wiki page.
23. Alert any community members who are awaiting for fixes either on the support forum or GitHub issues.