Revise pull request template (#4039)

* Revise pull request template

See below for the new language, to clarify that documentation is only necessary
for "user visible changes."

I added "including notable bug fixes" to indicate that minor bug fixes may not
be worth noting (I was thinking of test-suite only fixes in this category) but
perhaps that is too confusing.

* remove line break

* Update releasing notes

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,4 +3,5 @@
  - [ ] Closes #xxxx
  - [ ] Tests added
  - [ ] Passes `isort -rc . && black . && mypy . && flake8`
- - [ ] Fully documented, including `whats-new.rst` for all changes and `api.rst` for new API
+ - [ ] User visible changes (including notable bug fixes) are documented in `whats-new.rst`
+ - [ ] New functions/methods are listed in `api.rst`

HOW_TO_RELEASE.md

@@ -1,12 +1,21 @@
-How to issue an xarray release in 16 easy steps
+# How to issue an xarray release in 17 easy steps
 
 Time required: about an hour.
 
  1. Ensure your master branch is synced to upstream:
       ```
       git pull upstream master
       ```
- 2. Look over whats-new.rst and the docs. Make sure "What's New" is complete
+ 2. Get a list of contributors with:
+    ```
+    git log "$(git tag --sort="v:refname" | sed -n 'x;$p').." --format=%aN | sort -u | perl -pe 's/\n/$1, /'
+    ```
+    or by substituting the _previous_ release in:
+    ```
+    git log v0.X.Y-1.. --format=%aN | sort -u | perl -pe 's/\n/$1, /'
+    ```
+    Add these into `whats-new.rst` somewhere :)
+ 3. 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.
     Things to watch out for:
@@ -16,41 +25,41 @@ Time required: about an hour.
       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
       release.
- 3. If you have any doubts, run the full test suite one final time!
+ 4. If you have any doubts, run the full test suite one final time!
       ```
       pytest
       ```
- 4. Check that the ReadTheDocs build is passing.
- 5. On the master branch, commit the release in git:
+ 5. Check that the ReadTheDocs build is passing.
+ 6. On the master branch, commit the release in git:
       ```
       git commit -am 'Release v0.X.Y'
       ```
- 6. Tag the release:
+ 7. Tag the release:
       ```
       git tag -a v0.X.Y -m 'v0.X.Y'
       ```
- 7. Build source and binary wheels for pypi:
+ 8. Build source and binary wheels for pypi:
       ```
       git clean -xdf  # this deletes all uncommited changes!
       python setup.py bdist_wheel sdist
       ```
- 8. Use twine to check the package build:
+ 9. Use twine to check the package build:
       ```
       twine check dist/xarray-0.X.Y*
       ```
- 9. Use twine to register and upload the release on pypi. Be careful, you can't
+10. 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.
-10. Push your changes to master:
+11. Push your changes to master:
       ```
       git push upstream master
       git push upstream --tags
       ```
-11. Update the stable branch (used by ReadTheDocs) and switch back to master:
+12. Update the stable branch (used by ReadTheDocs) and switch back to master:
      ```
       git checkout stable
       git rebase master
@@ -60,7 +69,7 @@ Time required: about an hour.
     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.)
-12. Add a section for the next release (v.X.Y+1) to doc/whats-new.rst:
+13. Add a section for the next release (v.X.Y+1) to doc/whats-new.rst:
      ```
      .. _whats-new.0.X.Y+1:
 
@@ -86,19 +95,19 @@ Time required: about an hour.
      Internal Changes
      ~~~~~~~~~~~~~~~~
      ```
-13. Commit your changes and push to master again:
+14. Commit your changes and push to master again:
       ```
       git commit -am 'New whatsnew section'
       git push upstream master
       ```
     You're done pushing to master!
-14. Issue the release on GitHub. Click on "Draft a new release" at
+15. Issue the release on GitHub. Click on "Draft a new release" at
     https://github.com/pydata/xarray/releases. Type in the version number, but
     don't bother to describe it -- we maintain that on the docs instead.
-15. Update the docs. Login to https://readthedocs.org/projects/xray/versions/
+16. Update the docs. Login to https://readthedocs.org/projects/xray/versions/
     and switch your new release tag (at the bottom) from "Inactive" to "Active".
     It should now build automatically.
-16. Issue the release announcement! For bug fix releases, I usually only email
+17. Issue the release announcement! For bug fix releases, I usually only email
     xarray@googlegroups.com. For major/feature releases, I will email a broader
     list (no more than once every 3-6 months):
       - pydata@googlegroups.com
@@ -109,18 +118,8 @@ Time required: about an hour.
 
     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 substituting the _previous_ release in:
-    ```
-    git log v0.X.Y-1.. --format="%aN" | sort -u
-    ```
-    NB: copying this output into a Google Groups form can cause 
-    [issues](https://groups.google.com/forum/#!topic/xarray/hK158wAviPs) with line breaks, so take care
 
-Note on version numbering:
+## Note on version numbering
 
 We follow a rough approximation of semantic version. Only major releases (0.X.0)
 should include breaking changes. Minor releases (0.X.Y) are for bug fixes and