Skip to content

Commit

Permalink
docs: Tweak release docs and improve release build script (#7631)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@tofumatt
tofumatt committed Jul 2, 2018
1 parent 35a8399 commit 354756a
Show file tree
Hide file tree
Showing 2 changed files with 107 additions and 57 deletions.
88 changes: 55 additions & 33 deletions bin/build-plugin-zip.sh
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -66,35 +91,32 @@ 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
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 \
Expand All @@ -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! 🎉 "
76 changes: 52 additions & 24 deletions docs/reference/release.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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! 🎉

0 comments on commit 354756a

Please sign in to comment.