tree 0e181ed49a369b00187cbf38604dd4ac143c2d06
parent 99c0a345ea0a51f17d536eb272379660ebea4e99
author Han Seoul-Oh <laughinghan@gmail.com> 1466678005 -0700
committer Han Seoul-Oh <laughinghan@gmail.com> 1466706036 -0700

New 2-step release process: script/{prep,push}-release.sh

Steps:
1. On a clean tree on `master`, add a new entry to `CHANGELOG.md` in the
   same format as the other entries, then run `script/prep-release.sh`
   to do everything that can be done locally: bump version, build,
   package as tarball + zipfile, commit, tag.
2. After double-checking the build/package/commit/tag, run
   `script/push-release.sh` (with a GitHub access token env variable)
   to automatically publish to NPM, push to GitHub, create a new GitHub
   Release, and cleanup the tarballs etc.

Notes:
- `CHANGELOG.md`: I changed the format to resemble [the GitHub Releases
  page] more. In particular, each entry has a one-line summary on the
  GitHub Releases page that was the commit message for the version bump/
  changelog addition, but didn't show up in the changelog at all.
- `Makefile`: since these scripts create and cleanup the tarballs and
  zipfiles, there's no need for `make dist` anymore, and `make clean` is
  now, well, cleaner.
- Creating GitHub Releases: this was loosely inspired by the
  [gh-release Bash script], but was mostly based on the [GitHub Releases
  API docs].

[the GitHub Releases page] https://github.com/mathquill/mathquill/releases
[gh-release Bash script]: https://github.com/progrium/gh-release/blob/master/bash/gh-release.bash
[itHub Releases API docs]: https://developer.github.com/v3/repos/releases/#create-a-release

--

I designed this release process to have 2 steps:

1. Do everything that can be done locally: build, changelogs, bump
   version, commit, tag, create tarballs and zipfiles
2. Only after getting a chance to double-check the stuff done locally do
   we publish on public servers like NPM and GitHub

Not coincidentally, `npm` has two relevant commands, [`npm version`]
and [`npm publish`]. They seem like they'd correspond nicely with my
2 steps, so I tried implementing the release process as hooks into those
commands, but it was too annoying:
- [`npm version`] ensures that the working tree is clean even before
  calling the `preversion` hook, and then automatically commits, so
  the releaser would have to edit `CHANGELOG.md` during one of those
  hook calls (like it opens a shell or editor or something).
- [`npm publish`] is not as well-documented as `npm version`, but I
  [stumbled on] a sub-step: [`npm pack`], which figures out the files
  to be included and packs them into a tarball to be uploaded to the
  NPM registry. However, we actually want that to happen during the
  Step 1, so we can double-check it before uploading, not this step.

So using NPM hook scripts, the workflow would have to be:
1. On a clean tree, run `npm version patch`, which opens an editor on
   `CHANGELOG.md`, then builds, commits, tags, and in particular
   packages a tarball like `mathquill-0.10.2.tgz`.
2. After double-checking the build/package/commit/tag, run
   `npm publish mathquill-0.10.2.tgz`. Note that plain `npm publish`
   would re-run `npm pack` instead of using the tarball from Step 1.
   (I guess that would be fine, just inefficient?)

Rather than work within these inconveniences, I figured it'd be simpler
to just use "lower-level" tools, or at least, the same tools but in a
lower-level capacity. Specifically, `prep-release.sh` calls
`npm version --no-git-tag-version`, which just bumps the version in
package.json and doesn't do anything with Git, and then calls
`npm pack` to package the tarball; and `push-release.sh` calls
`npm publish <tarball>`, skipping the internal call to `npm pack` simply
using `npm publish` to upload to the NPM registry.

[`npm version`]: https://docs.npmjs.com/cli/version
[`npm publish`]: https://docs.npmjs.com/cli/publish
[`npm pack`]: https://docs.npmjs.com/cli/pack
[stumbled on]: https://github.com/npm/npm/pull/13080