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

Contributors who want to make a new release, follow these steps:

1. Copy these instructions into a Google Doc and share with those doing the release.
2. Create changelog draft on Wiki page.
   1. Gather props list of the entire release, including contributors of code, design, testing, project management, etc.
3. Update readme including the description, contributors, and screenshots (as needed).
4. For major release, draft blog post about the new release.
5. For minor releases, make sure all merged commits in develop have been also merged onto release branch.
   • To open all PRs that have been merged into the 1.5 branch since the 1.5.3 release: for num in $(git log 1.5.3...origin/1.5 --oneline | ack '(?<=#)\d+' -o | sort | uniq); do open "https://github.com/ampproject/amp-wp/issues/$num"; done
   • Make sure all milestoned issues and PRs match this set:

   git log 1.5.3...origin/1.5 --oneline | ack '(?<=#)\d+' -o | sort | uniq > prs-from-branch.txt
   diff prs-from-gh.txt prs-from-branch.txt

   • Make sure there are no duplicate entries by selecting the changelog contents and doing: pbpaste | ack '(?<=/)\d+' -o | sort | uniq -c.
   • Make sure the issues in the changelog match the issues in the milestone.
6. Check out the branch intended for release (develop for major, x.y for minor) and pull latest commits.
7. (Obsolete?) Delete the assets directory and re-checkout from Git to ensure that orphaned build files are removed.
8. (Maybe) Do npm install && composer selfupdate --2 && composer install --prefer-source --no-interaction && npm run build:prod.
9. 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.
   4. Commit and push.
10. Do npm install && composer selfupdate --2 && composer install --prefer-source --no-interaction && npm run build:prod.
11. Verify PHP 7.0 syntax compatibility of Composer-generated files.
12. Install the amp.zip onto a normal WordPress install running a stable release build; do smoke test to ensure it works.
13. 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 /tmp/amp-trunk/ ./build/ (instead of straight diff, it's best to use a GUI like idea diff, phpstorm diff, or opendiff).
14. 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. Add changelog entry to the release and link to compare view comparing previous release.
15. Verify the release branch has the pushed commit! Double check GHA.
16. Run npm run deploy to commit the plugin to WordPress.org.
17. Open confirmation email.
18. Click view changes and compare SVN diff with previous release.
19. Publish GitHub release.
20. Press to Confirm the release on WordPress.org.
21. Verify the release is available on WordPress.org; try installing it on a WordPress install and confirm it works.
22. 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.
23. For new major releases, create a release branch from the tag. Patch versions are made from the release branch.
24. Bump version in release branch. After major release (e.g. 1.2.0), bump to 1.3.0-alpha on develop; after minor release (e.g. 1.2.1) bump version to 1.2.2-alpha on the release branch.
25. 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 -
26. Update develop branch:
    1. Re-run npm install && composer install && npm run dev.
    2. For minor releases, bump Stable tag in the README.md in develop.
    3. Re-run wp amp docs generate, verify changes, and commit any docs updates.
27. Close the GitHub milestone.
28. Archive cards in project in Passed QA column.
29. Make any necessary changes to Development Builds Wiki page.
30. Publish release blog post (if applicable), including link to GitHub release.
31. Make announcements on Twitter and the #amp-wp channel on AMP Slack, linking to release post or GitHub release.
32. Alert any community members who are awaiting for fixes either on the support forum or GitHub issues.

(Stale) Changelog messages

• Changelog messages are added in the PR-related issue, within its reserved section, which is pre-populated from the issue template.
• Changelog messages start with a verb in its imperative form (e.g. “Fix bug xyz”), preferably one of the following words:
  • Add (for features)
  • Introduce (for features)
  • Enhance (for enhancements)
  • Improve (for enhancements)
  • Change (for misc changes)
  • Update (for misc changes)
  • Modify (for misc changes)
  • Remove (for removal)
  • Fix (for bug fixes)
  • N/A (skip changelog message)

(Stale) Changelog format

• The changelog messages are categorized as follows:
  • Added
  • Enhanced
  • Changed
  • Fixed
• Changelog messages are automatically assigned to one of the defined categories based on the first word the message starts with. Default: “Changed”.
• Changelogs with the message “N/A” are skipped.

Maintainers must ensure that changelog messages are clear and follow the formatting guidelines.