From 354756a95dcb4f5e224a80ac0388810b0be9e370 Mon Sep 17 00:00:00 2001 From: Matthew Riley MacPherson Date: Mon, 2 Jul 2018 16:46:18 +0100 Subject: [PATCH] docs: Tweak release docs and improve release build script (#7631) * docs: Tweak release docs and improve release build script Fixes #7607 This improves some wording/formatting of the release doc (it should look a lot better especially as output Markdown now), but more importantly stops the build script from removing files in someone's working directory without warning them first. It does this by doing a `--dry-run` of `git clean -xdf` and showing the user the output so they aren't surprised by doing a release and losing their work. I also prevented the build script from exiting with a non-zero status code, because this really uglies up the script output when an error occurs. I think it's nice to have the error in the script be the last thing the user sees, so this shows the error rather than the `npm run` error output from exiting with a non-zero status. Also I added some emoji whimsy because I'm like that. * docs: add notes about cherry-pick releases --- bin/build-plugin-zip.sh | 88 ++++++++++++++++++++++++--------------- docs/reference/release.md | 76 ++++++++++++++++++++++----------- 2 files changed, 107 insertions(+), 57 deletions(-) diff --git a/bin/build-plugin-zip.sh b/bin/build-plugin-zip.sh index 691f28b2dc0072..a1db03c6386aeb 100755 --- a/bin/build-plugin-zip.sh +++ b/bin/build-plugin-zip.sh @@ -1,21 +1,35 @@ #!/bin/bash -# Exit if any command fails +# Exit if any command fails. set -e -# Change to the expected directory +# Change to the expected directory. cd "$(dirname "$0")" cd .. -# Enable nicer messaging for build status +# Enable nicer messaging for build status. +BLUE_BOLD='\033[1;34m'; +GREEN_BOLD='\033[1;32m'; +RED_BOLD='\033[1;31m'; YELLOW_BOLD='\033[1;33m'; COLOR_RESET='\033[0m'; +error () { + echo -e "\n${RED_BOLD}$1${COLOR_RESET}\n" +} status () { + echo -e "\n${BLUE_BOLD}$1${COLOR_RESET}\n" +} +success () { + echo -e "\n${GREEN_BOLD}$1${COLOR_RESET}\n" +} +warning () { echo -e "\n${YELLOW_BOLD}$1${COLOR_RESET}\n" } -# Make sure there are no changes in the working tree. Release builds should be -# traceable to a particular commit and reliably reproducible. (This is not +status "πŸ’ƒ Time to release Gutenberg πŸ•Ί" + +# Make sure there are no changes in the working tree. Release builds should be +# traceable to a particular commit and reliably reproducible. (This is not # totally true at the moment because we download nightly vendor scripts). changed= if ! git diff --exit-code > /dev/null; then @@ -25,34 +39,45 @@ elif ! git diff --cached --exit-code > /dev/null; then fi if [ ! -z "$changed" ]; then git status - echo "ERROR: Cannot build plugin zip with dirty working tree." - echo " Commit your changes and try again." + error "ERROR: Cannot build plugin zip with dirty working tree. ☝️ + Commit your changes and try again." exit 1 fi branch="$(git rev-parse --abbrev-ref HEAD)" if [ "$branch" != 'master' ]; then - echo "WARNING: You should probably be running this script against the" - echo " 'master' branch (current: '$branch')" - echo + warning "WARNING: You should probably be running this script against the + 'master' branch (current: '$branch')" sleep 2 fi -# Remove ignored files to reset repository to pristine condition. Previous test -# ensures that changed files abort the plugin build. -status "Cleaning working directory..." -git clean -xdf +# Do a dry run of the repository reset. Prompting the user for a list of all +# files that will be removed should prevent them from losing important files! +status "Resetting the repository to pristine condition. ✨" +git clean -xdf --dry-run +warning "🚨 About to delete everything above! Is this okay? 🚨" +echo -n "[Y]es/[N]o: " +read answer +if [ "$answer" != "${answer#[Yy]}" ]; then + # Remove ignored files to reset repository to pristine condition. Previous + # test ensures that changed files abort the plugin build. + status "Cleaning working directory... πŸ›€" + git clean -xdf +else + error "Fair enough; aborting. Tidy up your repo and try again. πŸ™‚" + exit 1 +fi # Download all vendor scripts -status "Downloading remote vendor scripts..." +status "Downloading remote vendor scripts... πŸ›΅" vendor_scripts="" -# Using `command | while read...` is more typical, but the inside of the while +# Using `command | while read...` is more typical, but the inside of the `while` # loop will run under a separate process this way, meaning that it cannot -# modify $vendor_scripts. See: https://stackoverflow.com/a/16855194 +# modify $vendor_scripts. See: https://stackoverflow.com/a/16855194 exec 3< <( - # minified versions of vendor scripts + # Get minified versions of vendor scripts. php bin/get-vendor-scripts.php - # non-minified versions of vendor scripts (for SCRIPT_DEBUG) + # Get non-minified versions of vendor scripts (for SCRIPT_DEBUG). php bin/get-vendor-scripts.php debug ) while IFS='|' read -u 3 url filename; do @@ -66,26 +91,23 @@ while IFS='|' read -u 3 url filename; do --write-out "%{http_code}" ) if [ "$http_status" != 200 ]; then - echo "error - HTTP $http_status" + error "HTTP $http_status" exit 1 fi mv -f "vendor/_download.tmp.js" "vendor/$filename" - echo "done!" + echo -e "${GREEN_BOLD}done!${COLOR_RESET}" vendor_scripts="$vendor_scripts vendor/$filename" done -# Run the build -status "Installing dependencies..." +# Run the build. +status "Installing dependencies... πŸ“¦" npm install -status "Generating build..." +status "Generating build... πŸ‘·β€β™€οΈ" npm run build -status "Generating PHP file for wordpress.org to parse translations..." +status "Generating PHP file for wordpress.org to parse translations... πŸ‘·β€β™‚οΈ" npx pot-to-php ./languages/gutenberg.pot ./languages/gutenberg-translations.php gutenberg -# Remove any existing zip file -rm -f gutenberg.zip - -# Temporarily modify `gutenberg.php` with production constants defined. Use a +# Temporarily modify `gutenberg.php` with production constants defined. Use a # temp file because `bin/generate-gutenberg-php.php` reads from `gutenberg.php` # so we need to avoid writing to that file at the same time. php bin/generate-gutenberg-php.php > gutenberg.tmp.php @@ -93,8 +115,8 @@ mv gutenberg.tmp.php gutenberg.php build_files=$(ls build/*/*.{js,css}) -# Generate the plugin zip file -status "Creating archive..." +# Generate the plugin zip file. +status "Creating archive... 🎁" zip -r gutenberg.zip \ gutenberg.php \ lib/*.php \ @@ -106,7 +128,7 @@ zip -r gutenberg.zip \ languages/gutenberg-translations.php \ README.md -# Reset `gutenberg.php` +# Reset `gutenberg.php`. git checkout gutenberg.php -status "Done." +success "Done. You've built Gutenberg! πŸŽ‰ " diff --git a/docs/reference/release.md b/docs/reference/release.md index 71d1e3b009b571..f11511854634b1 100644 --- a/docs/reference/release.md +++ b/docs/reference/release.md @@ -4,51 +4,79 @@ This document is a checklist for building and releasing a new version of Gutenbe ## Writing the Release Post and Changelog -* Open the [recently updated PRs view](https://github.com/WordPress/gutenberg/pulls?q=is%3Apr+is%3Aclosed+sort%3Aupdated-desc), and find the PR where the last version bump occurred. -* Read through each PR since then, to determine if it needs to be included in the Release Post and/or changelog. -* Choose a feature or two to highlight in the release post - record an animation of them in action. +* Open the [recently updated PRs view](https://github.com/WordPress/gutenberg/pulls?q=is%3Apr+is%3Aclosed+sort%3Aupdated-desc) and find the PR where the last version bump occurred. +* Read through each PR since the last version bump to determine if it needs to be included in the Release Post and/or changelog. +* Choose a feature or two to highlight in the release post–record an animation of them in action. * Save the draft post on [make.wordpress.org/core](https://make.wordpress.org/core/), for publishing after the release. ## Bumping the Version * Create a PR like [this one](https://github.com/WordPress/gutenberg/pull/3479/files), bumping the version number in `gutenberg.php`, `package.json`, and `package-lock.json`. -* Check that there's no work in progress that's just about to land, and inform committers to hold off on merging any changes until after the release process is complete. +* Check that there's no work-in-progress that's just about to land. [Inform committers in `#core-editor` on Slack](https://make.wordpress.org/chat/) to hold off on merging any changes until after the release process is complete. * Merge the version bump PR. +### For Patch Releases Done via `git cherry-pick` + +If you're creating a bugfix release which is cherry-picked instead of tagged from `master` (example: https://github.com/WordPress/gutenberg/compare/v3.1.0…v3.1.1), you should go about things a bit differently: + +1. Check out the last release (for example: `git checkout v3.1.0`). +2. Cherry-pick commits (in chronological order) with `git cherry-pick [SHA]`. +3. Tag this release and push it to GitHub: +```bash +git tag v3.1.1 +git push origin v3.1.1 +``` +4. Create a merge PR against master that only bumps the version number in `gutenberg.php`, `package.json`, and `package-lock.json`. + ## Build the Release Note: The `1.x.0` notation `git` and `svn` commands should be replaced with the version number of the new release. -* `git checkout master` and `git pull` - (make sure your local master is up to date, you can confirm by checking `gutenberg.php` and noting the version bump you merged previously.) -* Run the command `npm run package-plugin` from the root of project. This packages a zip file with the final builds. -* Check the zip file looks good. Drop it in the #core-editor channel for people to test. Again, make sure if you unzip the file that the version numbers is correct. +* Run `git checkout master` and `git pull`. Make sure your local `master` is up to date; you can confirm this by opening `gutenberg.php` and checking for the version bump you merged previously. +* Run `./bin/build-plugin-zip.sh` from the root of project. This packages a zip file with a release build of `gutenberg.zip`. +* Check that the zip file looks good. Drop it in the [`#core-editor` channel](https://wordpress.slack.com/messages/C02QB2JS7) for people to test. Again: make sure if you unzip the file that the version number is correct. * Run `git tag v1.x.0` from `master` branch (with the new version we are shipping). -* `git push --tags` +* Run `git push --tags`. ## Push the Release -* Have a checkout of https://wordpress.org/plugins/gutenberg/. - First time: `svn checkout https://plugins.svn.wordpress.org/gutenberg` - Subsequent times: `svn up` -* Delete the contents of `trunk` except for the `readme.txt` and `changelog.txt` files (these files don’t exist in github, only on svn). -* Copy all the contents of the zip file to `trunk`. -* Edit `readme.txt` to include the changelog for the current release, replacing the previous release's. +You'll need to use Subversion to publish the plugin to WordPress.org. + +* Do an SVN checkout of `https://wordpress.org/plugins/gutenberg/`: + * If this is your first checkout, run: `svn checkout https://plugins.svn.wordpress.org/gutenberg` + * If you already have a copy, run: `svn up` +* Delete the contents of `trunk` except for the `readme.txt` and `changelog.txt` files (these files don’t exist in the git repo, only in subversion). +* Extract the contents of the zip file to `trunk`. +* Edit `readme.txt`, replacing the changelog for the previous version with the current release's changelog. * Add the changelog for the current release to `changelog.txt`. * Add new files to the SVN repo, and remove old files, in the `trunk` directory: - Add new files: `svn st | grep '^\?' | awk '{print $2}' | xargs svn add` - Delete old files: `svn st | grep '^!' | awk '{print $2}' | xargs svn rm` +```bash +# Add new files: +svn st | grep '^\?' | awk '{print $2}' | xargs svn add +# Delete old files: +svn st | grep '^!' | awk '{print $2}' | xargs svn rm +``` + * Commit the new version to `trunk`: - `svn ci -m "Committing version 1.x.0"` +```bash +svn ci -m "Committing version 1.x.0" +``` + * Tag the new version. Change to the parent directory, and run: - `svn cp trunk tags/1.x.0` - `svn ci -m "Tagging version 1.x.0."` -* Edit `trunk/readme.txt` to point to the new tag. The `Stable version` header in `readme.txt` should be updated to match the new release version number. After updating and committing that, the new version will be released: - `svn ci -m "Releasing version 1.x.0"` +```bash +svn cp trunk tags/1.x.0 +svn ci -m "Tagging version 1.x.0." +``` + +* Edit `trunk/readme.txt` to point to the new tag. The **Stable version** header in `readme.txt` should be updated to match the new release version number. After updating and committing that, the new version will be released: +```bash +svn ci -m "Releasing version 1.x.0" +``` -## Post Release +## Post-Release * Check that folks are able to install the new version from their Dashboard. * Publish the make/core post. +* Pat yourself on the back! πŸ‘ -Tada! πŸŽ‰ +Ta-da! πŸŽ‰