| commit | 44ab36c3d804b4d10e83ae073340650b6674e728 | [log] [tgz] |
|---|---|---|
| author | Han Seoul-Oh <laughinghan@gmail.com> | Thu Jun 23 03:33:25 2016 -0700 |
| committer | Han Seoul-Oh <laughinghan@gmail.com> | Thu Jun 23 11:20:36 2016 -0700 |
| tree | 0e181ed49a369b00187cbf38604dd4ac143c2d06 | |
| parent | 99c0a345ea0a51f17d536eb272379660ebea4e99 [diff] |
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
by Han, Jeanine, and Mary (maintainers@mathquill.com)
MathQuill is a web formula editor designed to make typing math easy and beautiful.
The MathQuill project is supported by its partners. We hold ourselves to a compassionate Code of Conduct.
MathQuill is resuming active development and we‘re committed to getting things running smoothly. Find a dusty corner? Let us know in Slack. (Prefer IRC? We’re #mathquill on Freenode.)
MathQuill has a simple interface. This brief example creates a MathQuill element and renders, then reads a given input:
var htmlElement = document.getElementById('some_id'); var config = { handlers: { edit: function(){ ... } }, restrictMismatchedBrackets: true }; var mathField = MQ.MathField(htmlElement, config); mathField.latex('2^{\\frac{3}{2}}'); // Renders the given LaTeX in the MathQuill field mathField.latex(); // => '2^{\\frac{3}{2}}'
Check out our Getting Started Guide for setup instructions and basic MathQuill usage.
Most documentation for MathQuill is located on ReadTheDocs.
Some older documentation still exists on the Wiki.
The Source Code Form of MathQuill is subject to the terms of the Mozilla Public License, v. 2.0: http://mozilla.org/MPL/2.0/
The quick-and-dirty is you can do whatever if modifications to MathQuill are in public GitHub forks. (Other ways to publicize modifications are also fine, as are private use modifications. See also: MPL 2.0 FAQ)