Refinements to how-to-release (#4964)

Author: max-sixty

HOW_TO_RELEASE.md

@@ -21,9 +21,9 @@ upstream        https://github.com/pydata/xarray (push)
  2. Confirm there are no commits on stable that are not yet merged
     ([ref](https://github.com/pydata/xarray/pull/4440)):
      ```sh
-     git merge upstream stable
+     git merge upstream/stable
      ```
- 2. Add a list of contributors with:
+ 3. Add a list of contributors with:
     ```sh
     git log "$(git tag --sort="v:refname" | sed -n 'x;$p').." --format=%aN | sort -u | perl -pe 's/\n/$1, /'
     ```
@@ -35,9 +35,9 @@ upstream        https://github.com/pydata/xarray (push)
     ```sh
     git log v{0.X.Y-1}.. --format=%aN | sort -u | wc -l
     ```
- 3. Write a release summary: ~50 words describing the high level features. This
+ 4. Write a release summary: ~50 words describing the high level features. This
     will be used in the release emails, tweets, GitHub release notes, etc.
- 4. Look over whats-new.rst and the docs. Make sure "What's New" is complete
+ 5. Look over whats-new.rst and the docs. Make sure "What's New" is complete
     (check the date!) and add the release summary at the top.
     Things to watch out for:
     - Important new features should be highlighted towards the top.
@@ -46,46 +46,48 @@ upstream        https://github.com/pydata/xarray (push)
       due to a bad merge. Check for these before a release by using git diff,
       e.g., `git diff v{0.X.Y-1} whats-new.rst` where {0.X.Y-1} is the previous
       release.
- 5. If possible, open a PR with the release summary and whatsnew changes.
- 6. After merging, again ensure your master branch is synced to upstream:
+ 6. Open a PR with the release summary and whatsnew changes; in particular the
+    release headline should get feedback from the team on what's important to include.
+ 7. After merging, again ensure your master branch is synced to upstream:
      ```sh
      git pull upstream master
      ```
- 7. If you have any doubts, run the full test suite one final time!
+ 8. If you have any doubts, run the full test suite one final time!
       ```sh
       pytest
       ```
- 8. Check that the ReadTheDocs build is passing.
- 9. On the master branch, commit the release in git:
-      ```sh
-      git commit -am 'Release v{0.X.Y}'
-      ```
+ 9. Check that the ReadTheDocs build is passing.
 10. Tag the release:
       ```sh
       git tag -a v{0.X.Y} -m 'v{0.X.Y}'
       ```
-11. Build source and binary wheels for PyPI:
+11. Ensure the dependencies for building are installed:
       ```sh
-      git clean -xdf  # this deletes all uncommitted changes!
+      pip install setuptools-scm twine wheel
+      ```
+12. Build source and binary wheels for PyPI:
+      ```sh
+      git clean -xdf  # This removes any untracked files!
+      git restore -SW .  # This removes any tracked changes!
       python setup.py bdist_wheel sdist
       ```
-12. Use twine to check the package build:
+13. Use twine to check the package build:
       ```sh
       twine check dist/xarray-{0.X.Y}*
       ```
-13. Use twine to register and upload the release on PyPI. Be careful, you can't
+14. Use twine to register and upload the release on PyPI. Be careful, you can't
     take this back!
       ```sh
       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.
-14. Push your changes to master:
+15. Push your changes to master:
       ```sh
       git push upstream master
       git push upstream --tags
       ```
-15. Update the stable branch (used by ReadTheDocs) and switch back to master:
+16. Update the stable branch (used by ReadTheDocs) and switch back to master:
      ```sh
       git switch stable
       git rebase master
@@ -95,18 +97,22 @@ upstream        https://github.com/pydata/xarray (push)
     It's OK to force push to `stable` if necessary. (We also update the stable
     branch with `git cherry-pick` for documentation only fixes that apply the
     current released version.)
-16. Add a section for the next release {0.X.Y+1} to doc/whats-new.rst:
+17. Add a section for the next release {0.X.Y+1} to doc/whats-new.rst:
      ```rst
      .. _whats-new.{0.X.Y+1}:
 
      v{0.X.Y+1} (unreleased)
      ---------------------
 
+     New Features
+     ~~~~~~~~~~~~
+
+
      Breaking changes
      ~~~~~~~~~~~~~~~~
 
 
-     New Features
+     Deprecations
      ~~~~~~~~~~~~
 
 
@@ -120,20 +126,21 @@ upstream        https://github.com/pydata/xarray (push)
 
      Internal Changes
      ~~~~~~~~~~~~~~~~
+
      ```
-17. Commit your changes and push to master again:
+18. Commit your changes and push to master again:
       ```sh
       git commit -am 'New whatsnew section'
       git push upstream master
       ```
     You're done pushing to master!
-18. Issue the release on GitHub. Click on "Draft a new release" at
+19. Issue the release on GitHub. Click on "Draft a new release" at
     <https://github.com/pydata/xarray/releases>. Type in the version number
     and paste the release summary in the notes.
-19. Update the docs. Login to <https://readthedocs.org/projects/xray/versions/>
+20. 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.
-20. Issue the release announcement to mailing lists & Twitter. For bug fix releases, I
+21. Issue the release announcement to mailing lists & Twitter. 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]