Tweaks to release instructions (pydata#3555)

* tweaks to release instructions

* Update HOW_TO_RELEASE.md

Co-Authored-By: keewis <[email protected]>

* no need for --reverse either

* add cool script as option from @keewis

* whatsnew reference

* tweak

HOW_TO_RELEASE → HOW_TO_RELEASE.md

@@ -1,9 +1,11 @@
-How to issue an xarray release in 15 easy steps
+How to issue an xarray release in 14 easy steps
 
 Time required: about an hour.
 
  1. Ensure your master branch is synced to upstream:
-       git pull upstream master
+      ```
+      git pull upstream master
+      ```
  2. Look over whats-new.rst and the docs. Make sure "What's New" is complete
     (check the date!) and consider adding a brief summary note describing the
     release at the top.
@@ -12,37 +14,53 @@ Time required: about an hour.
     - Function/method references should include links to the API docs.
     - Sometimes notes get added in the wrong section of whats-new, typically
       due to a bad merge. Check for these before a release by using git diff,
-      e.g., ``git diff v0.X.Y whats-new.rst`` where 0.X.Y is the previous
+      e.g., `git diff v0.X.Y whats-new.rst` where 0.X.Y is the previous
       release.
  3. If you have any doubts, run the full test suite one final time!
-      py.test
+      ```
+      pytest
+      ```
  4. On the master branch, commit the release in git:
+      ```
       git commit -a -m 'Release v0.X.Y'
+      ```
  5. Tag the release:
+      ```
       git tag -a v0.X.Y -m 'v0.X.Y'
+      ```
  6. Build source and binary wheels for pypi:
+      ```
       git clean -xdf  # this deletes all uncommited changes!
       python setup.py bdist_wheel sdist
+      ```
  7. Use twine to register and upload the release on pypi. Be careful, you can't
     take this back!
+      ```
       twine upload dist/xarray-0.X.Y*
+      ```
     You will need to be listed as a package owner at
     https://pypi.python.org/pypi/xarray for this to work.
  8. Push your changes to master:
+      ```
       git push upstream master
       git push upstream --tags
+      ```
  9. Update the stable branch (used by ReadTheDocs) and switch back to master:
+     ```
       git checkout stable
       git rebase master
       git push upstream stable
       git checkout master
-    It's OK to force push to 'stable' if necessary.
-    We also update the stable branch with `git cherrypick` for documentation
-    only fixes that apply the current released version.
+     ```
+    It's OK to force push to 'stable' if necessary. (We also update the stable 
+    branch with `git cherrypick` for documentation only fixes that apply the 
+    current released version.)
 10. Add a section for the next release (v.X.(Y+1)) to doc/whats-new.rst.
 11. Commit your changes and push to master again:
-      git commit -a -m 'Revert to dev version'
+      ```
+      git commit -a -m 'New whatsnew section'
       git push upstream master
+      ```
     You're done pushing to master!
 12. Issue the release on GitHub. Click on "Draft a new release" at
     https://github.com/pydata/xarray/releases. Type in the version number, but
@@ -53,11 +71,22 @@ Time required: about an hour.
 14. Issue the release announcement! For bug fix releases, I usually only email
     [email protected]. For major/feature releases, I will email a broader
     list (no more than once every 3-6 months):
-      [email protected], [email protected],
-      [email protected], [email protected],
-      [email protected]
+      - [email protected]
+      - [email protected]
+      - [email protected]
+      - [email protected]
+      - [email protected]
+
     Google search will turn up examples of prior release announcements (look for
     "ANN xarray").
+    You can get a list of contributors with:
+    ```
+    git log "$(git tag --sort="v:refname" | sed -n 'x;$p').." --format="%aN" | sort -u
+    ```
+    or by replacing `v0.X.Y` with the _previous_ release in:
+    ```
+    git log v0.X.Y.. --format="%aN" | sort -u
+    ```
 
 Note on version numbering:
 

doc/whats-new.rst

@@ -13,7 +13,7 @@ What's New
     import xarray as xr
     np.random.seed(123456)
 
-.. _whats-new.0.14.1:
+.. _whats-new.0.15.0:
 
 
 v0.15.0 (unreleased)