tidepool-org/tools — pull request #3 by bewest (2014-02-27 23:41:26+00:00)
Title: discuss preparing an npm module for release from git

The tool uses git-extras to automatically prepare a repo for "release"-like
status. It increments the version number in package.json using the same
semantics as `npm version`, in addition to preparing some release notes
specific to this release.

It was designed with the following priorities:
* I wanted a tool which would allow me to create a pull request on a branch
to allow previewing and discussing the release.
* After previewing and discussing, it gets merged into master, and I manually
push the tag back to github using `git push --tags origin`.

I often use this to preview the commits and the results of the process, and I
like having most of the manual labor automated. The git-release tool in
git-extras automatically performs network operations, which I disagree with. I
want the opportunity to preview what has happened before sending it over the
network.

Using this tool has allowed me to expose and fix errors performed by myself and
others.

The tool also makes it easy to communicate what is in an individual release, in
terms of one-line commit summaries very easy. If the commit one-lines are
written well, this can be a good way to prepare more of a narrative of the
release, with hints on what to test. Once everyone is happy with the release,
it's easy to merge, and perform the network activity to officially publish it
with confidence.

Consequently the automation here is intended to address those two aspects of
preparing releases:
* previewing, obtaining visibility, and achieving consensus on releases of
"official code" published by tidepool
* finding and fixing problems caused by manually tagging/versioning things

How to deal with release notes, formatting, etc, isn't really the primary
objective here, just being able to reliably produce an upgraded npm module.

A few caveats, the name
* `./prep_repo_release.sh` leaves something to be desired
* What happens to release notes is very much up for discussion
I did the minimum thing to provide some record of version specific
releases. If we have a policy for release notes, the tool can be ammended
to do that. I found git-changelog to be a helpful starting place. This
seems like a reasonable starting place for discussing how we might want to
save some manual effort on release notes.

* It looks more dangerous than it is. npm version modifies your git repo,
for better or worse. The reset undos the damage done to the repo by npm,
and ensures that the commits are automatically generated do not happen on
the master branch. It also provides a better pivot point for defining the
tagging mechanism actually works, eg this is a reasonable starting point
for adding a segment that PGP signs the tag using tidepool.org address,
perhaps using the release notes for the tag annotation, etc...