Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update release guide #5274

Merged
merged 6 commits into from
May 13, 2021
Merged

Update release guide #5274

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
841efd6
simplified by GH action uploading to PyPI
TomNicholas May 6, 2021
aa8e96e
removed braces around version number in docs [skip-ci]
TomNicholas May 12, 2021
b4ec088
whats new [skip-ci]
TomNicholas May 12, 2021
c8c8d99
fixed link to PR [skip-ci]
TomNicholas May 12, 2021
a9cbf80
Merge remote-tracking branch 'upstream/master' into update_release_guide
dcherian May 13, 2021
871db62
Minor whats-new fix [skip-ci]
dcherian May 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 17 additions & 39 deletions HOW_TO_RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# How to issue an xarray release in 20 easy steps
# How to issue an xarray release in 16 easy steps

Time required: about an hour.

Expand Down Expand Up @@ -57,47 +57,26 @@ upstream https://github.com/pydata/xarray (push)
pytest
```
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}'
```
Comment on lines -60 to -63
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

isn't the tag still necessary?

Also, I would do the update of the release date in this step, in a extra commit with the message Release v0.X.Y, and then do the tag on that:

git tag -a v0.X.Y -m 'v0.X.Y'

The advantage is that if the release is delayed but the whats-new.rst PR is already merged (e.g. because a bug that has to be fixed before the release was found), the date won't be wrong.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure - I didn't do that step earlier...

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you definitely created a tag, but with a different command, probably? The date was updated in the release notes PR.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think when I clicked on the github button to make a new release it must have created the new tag then?

Copy link
Collaborator

@keewis keewis May 6, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that could be it. It might be worth keeping that step manual, though: if the build is broken (e.g. because a build dependency is missing / outdated) you don't have to delete / re-create the release.

Copy link
Collaborator

@alexamici alexamici May 7, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When you create a draft release GitHub creates the tag and kicks the normal GA.

When you publish the release (after checking that tests have passed) GitHub kicks the release GA.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, good to know, I never used github to create tags. This still feels a bit strange because you'd have to delete / re-create the draft release to rerun the CI (not sure how much of an issue that is), and there's the really minor issue of not being able to set the tag message, which means that the message of the last commit will show up in the overview (hidden behind ...).

11. Ensure the dependencies for building are installed:
```sh
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
```
13. Use twine to check the package build:
```sh
twine check dist/xarray-{0.X.Y}*
```
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.
15. Push your changes to master:
```sh
git push upstream master
git push upstream --tags
```
16. Update the stable branch (used by ReadTheDocs) and switch back to master:
10. Issue the release on GitHub. Click on "Draft a new release" at
<https://github.com/pydata/xarray/releases>. Type in the version number (with a "v")
and paste the release summary in the notes.
11. This should automatically trigger an upload of the new build to PyPI via GitHub Actions.
Check this has run [here](https://github.com/pydata/xarray/actions/workflows/pypi-release.yaml),
and that the version number you expect is displayed [on PyPI](https://pypi.org/project/xarray/)
12. Update the stable branch (used by ReadTheDocs) and switch back to master:
```sh
git switch stable
git rebase master
git push --force upstream stable
git switch master
```
You may need to first fetch it with `git fetch upstream`,
and check out a local version with `git checkout -b stable upstream/stable`.

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.)
17. Add a section for the next release {0.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:
```rst
.. _whats-new.{0.X.Y+1}:
TomNicholas marked this conversation as resolved.
Show resolved Hide resolved

Expand Down Expand Up @@ -128,19 +107,17 @@ upstream https://github.com/pydata/xarray (push)
~~~~~~~~~~~~~~~~

```
18. Commit your changes and push to master again:
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!
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.
20. Update the docs. Login to <https://readthedocs.org/projects/xray/versions/>

15. 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.
21. Issue the release announcement to mailing lists & Twitter. For bug fix releases, I
16. 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
Expand All @@ -151,6 +128,7 @@ upstream https://github.com/pydata/xarray (push)

Google search will turn up examples of prior release announcements (look for
"ANN xarray").
Some of these groups require you to be subscribed in order to email them.

<!-- markdownlint-enable MD013 -->

Expand Down