Update release instructions (#373)

* Add release instructions

* PR feedback

* Add steps to push to test-pypi

* More feedback: test-release, and deploying latest

* Update release instructions

* Mention CHANGELOG.md

Author: msteffen

contributing.md

@@ -119,11 +119,43 @@ make docs
 
 ## Releasing
 
-To make a new release, from the master branch:
-
-* Rebuild docs to make sure they're in sync
-* Update `CHANGELOG.md` and `version.json`
-
-```bash
-make release
-```
+Our current process for publishing a release of python-pachyderm consists of the following steps:
+
+#### Validate the release
+- [ ] Ensure that `version.json` contains the `python-pachyderm` version to be released
+  - If `version.json` contains an already-released version of python-pachyderm, update it in a PR.
+- [ ] Ensure the protobufs are up-to-date
+  - Make sure `version.json` references the most recent compatible release of Pachyderm
+  - Run `make src/python_pachyderm/proto/v2`, and make sure that the generated code is unchanged
+  - If it's outdated, update it in a PR
+- [ ] Ensure the docs are up-to-date
+  - Rebuild the docs (with `make docs`), and make sure the generated docs are unchanged
+  - Merge any changes in a PR
+- [ ] Ensure `CHANGELOG.md` is up-to-date
+  - Commit any additional change notes in a PR.
+
+#### Test everything
+This is mostly necessary for major releases, but it always reduces risk.
+  - [ ] Deploy the version of pachyderm that matches `version.json` (the latest compatible release) and run our test suite.
+    - Make sure to install a matching version of `pachctl`, as e.g. python-pachyderm's `Mount()` implementation depends on `pachctl`
+  - [ ] Run `make lint` and ensure there are no errors
+  - [ ] Ensure that all examples still pass:
+    - [ ] All examples in the `examples/` dir (they must be run manually—`tox example` only runs `examples/opencv`)
+    - [ ] [Pachyderm's spouts101 example](github.com/pachyderm/pachyderm/tree/master/examples/spouts101), which should match `examples/spouts101` in this repo, but it's good to confirm
+
+#### Make Pypi release
+  - [ ] Run `make test-release`, which will checkout the release branch, build a package, and push it to test-pypi.
+    - Proofread the release page, as pypi doesn't allow you to modify a release after pushing it.
+  - [ ] Run `make release` which will re-build python-pachyderm and push a final version to pypi.
+
+#### Make GitHub release
+  - [ ] Go to http://github.com/pachyderm/python-pachyderm and create a new GitHub release pointing at the Git commit that was just pushed to pypi
+    - Include any notes added to `CHANGELOG.md` for this release
+  - [ ] (Only when releasing from `master`) Create a new branch for patch releases called `vA.B.x`. For example, if releasing 1.0.0, create a new `v1.0.x` branch to hold future patch-sized changes made to 1.0.0.
+
+#### Update versions for next release
+  - [ ] In the patch release branch (e.g. `v1.0.x`), create a PR to update the python-pachyderm version in `version.json` to contain the next _patch_ release (e.g. 1.0.1)
+    - This is the python-pachyderm version that is currently in development in that branch.
+  - [ ] (Only when releasing from `master`) In `master`, create a PR to update the python-pachyderm version in `version.json` to contain the next _minor_ release (e.g. 1.1.0)
+    - This is the python-pachyderm version that is currently in development in `master`.
+  - [ ] (Only when releasing from `master`) In the new patch release branch (e.g. `v1.0.x`), create a PR (or add to the above PR) to update `make release` so that it checks out `v1.0.x` instead of `master` when releasing from this branch.