diff --git a/HOW_TO_RELEASE.md b/HOW_TO_RELEASE.md index c890d61d966..24995a389c4 100644 --- a/HOW_TO_RELEASE.md +++ b/HOW_TO_RELEASE.md @@ -2,78 +2,92 @@ Time required: about an hour. +These instructions assume that `upstream` refers to the main repository: +``` +$ git remote -v +{...} +upstream https://github.com/pydata/xarray (fetch) +upstream https://github.com/pydata/xarray (push) +``` + 1. Ensure your master branch is synced to upstream: - ``` - git pull upstream master - ``` + ```sh + git pull upstream master + ``` 2. Get 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, /' ``` - or by substituting the _previous_ release in: - ``` - git log v0.X.Y-1.. --format=%aN | sort -u | perl -pe 's/\n/$1, /' + or by substituting the _previous_ release in {0.X.Y-1}: + ```sh + git log v{0.X.Y-1}.. --format=%aN | sort -u | perl -pe 's/\n/$1, /' ``` Add these into `whats-new.rst` somewhere :) + 2. Write a release summary: ~50 words describing the high level features. This + will be used in the release emails, tweets, GitHub release notes, etc. 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. + (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. - 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 v{0.X.Y-1} whats-new.rst` where {0.X.Y-1} is the previous release. + 4. If possible, open a PR with the release summary and whatsnew changes. + 4. After merging, again ensure your master branch is synced to upstream: + ```sh + git pull upstream master + ``` 4. If you have any doubts, run the full test suite one final time! - ``` + ```sh pytest ``` 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' + ```s + git commit -am 'Release v{0.X.Y}' ``` 7. Tag the release: + ```sh + git tag -a v{0.X.Y} -m 'v{0.X.Y}' ``` - git tag -a v0.X.Y -m 'v0.X.Y' - ``` - 8. Build source and binary wheels for pypi: - ``` - git clean -xdf # this deletes all uncommited changes! + 8. Build source and binary wheels for PyPI: + ```sh + git clean -xdf # this deletes all uncommitted changes! python setup.py bdist_wheel sdist ``` 9. Use twine to check the package build: + ```sh + twine check dist/xarray-{0.X.Y}* ``` - twine check dist/xarray-0.X.Y* - ``` -10. 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* + ```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. 11. Push your changes to master: - ``` + ```sh git push upstream master git push upstream --tags ``` 12. Update the stable branch (used by ReadTheDocs) and switch back to master: - ``` + ```sh git checkout stable git rebase master - git push upstream stable + git push --force 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 + branch with `git cherry-pick` for documentation only fixes that apply the current released version.) -13. Add a section for the next release (v.X.Y+1) to doc/whats-new.rst: +13. Add a section for the next release {0.X.Y+1} to doc/whats-new.rst: ``` - .. _whats-new.0.X.Y+1: + .. _whats-new.{0.X.Y+1}: - v0.X.Y+1 (unreleased) + v{0.X.Y+1} (unreleased) --------------------- Breaking changes @@ -96,19 +110,19 @@ Time required: about an hour. ~~~~~~~~~~~~~~~~ ``` 14. 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! 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. + https://github.com/pydata/xarray/releases. Type in the version number + and paste the release summary in the notes. 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. -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 +17. 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 - xarray@googlegroups.com diff --git a/doc/whats-new.rst b/doc/whats-new.rst index e109633a5e1..d85fa0dee14 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -117,8 +117,8 @@ New Features :py:func:`combine_by_coords` and :py:func:`combine_nested` using combine_attrs keyword argument. (:issue:`3865`, :pull:`3877`) By `John Omotani `_ -- 'missing_dims' argument to :py:meth:`Dataset.isel`, - `:py:meth:`DataArray.isel` and :py:meth:`Variable.isel` to allow replacing +- `missing_dims` argument to :py:meth:`Dataset.isel`, + :py:meth:`DataArray.isel` and :py:meth:`Variable.isel` to allow replacing the exception when a dimension passed to ``isel`` is not present with a warning, or just ignore the dimension. (:issue:`3866`, :pull:`3923`) By `John Omotani `_ @@ -132,7 +132,7 @@ New Features By `Stephan Hoyer `_. - Allow plotting of boolean arrays. (:pull:`3766`) By `Marek Jacob `_ -- Enable using MultiIndex levels as cordinates in 1D and 2D plots (:issue:`3927`). +- Enable using MultiIndex levels as coordinates in 1D and 2D plots (:issue:`3927`). By `Mathias Hauser `_. - A ``days_in_month`` accessor for :py:class:`xarray.CFTimeIndex`, analogous to the ``days_in_month`` accessor for a :py:class:`pandas.DatetimeIndex`, which