diff --git a/HOW_TO_RELEASE.md b/HOW_TO_RELEASE.md index 5352d427909..e30b05c40e2 100644 --- a/HOW_TO_RELEASE.md +++ b/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 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 . Type in the version number and paste the release summary in the notes. -19. Update the docs. Login to +20. Update the docs. Login to 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 xarray@googlegroups.com. For major/feature releases, I will email a broader list (no more than once every 3-6 months): - pydata@googlegroups.com