Skip to content

Commit

Permalink
update release steps (#6214)
Browse files Browse the repository at this point in the history 
- no more stable branch
- switch to calver
  • Loading branch information
Joe Hamman authored Jan 31, 2022
1 parent 0a1e7e4 commit e8d4239
Showing 1 changed file with 18 additions and 44 deletions.
62 changes: 18 additions & 44 deletions HOW_TO_RELEASE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,65 +18,47 @@ upstream https://github.com/pydata/xarray (push)
git switch main
git pull upstream main
```
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
```
3. Add a list of contributors with:
2. Add a list of contributors with:
```sh
git log "$(git tag --sort=v:refname | tail -1).." --format=%aN | sort -u | perl -pe 's/\n/$1, /'
```
This will return the number of contributors:
```sh
git log "$(git tag --sort=v:refname | tail -1).." --format=%aN | sort -u | wc -l
```
4. Write a release summary: ~50 words describing the high level features. This
3. Write a release summary: ~50 words describing the high level features. This
will be used in the release emails, tweets, GitHub release notes, etc.
5. Look over whats-new.rst and the docs. Make sure "What's New" is complete
4. 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.
- 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 v{0.X.Y-1} whats-new.rst` where {0.X.Y-1} is the previous
e.g., `git diff v{YYYY.MM.X-1} whats-new.rst` where {YYYY.MM.X-1} is the previous
release.
6. Open a PR with the release summary and whatsnew changes; in particular the
5. 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 main branch is synced to upstream:
6. After merging, again ensure your main branch is synced to upstream:
```sh
git pull upstream main
```
8. If you have any doubts, run the full test suite one final time!
7. If you have any doubts, run the full test suite one final time!
```sh
pytest
```
9. Check that the ReadTheDocs build is passing.
10. Issue the release on GitHub. Click on "Draft a new release" at
8. Check that the ReadTheDocs build is passing on the `main` branch.
9. 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.
10. 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 main:
```sh
git switch stable
git rebase main
git push --force upstream stable
git switch main
```
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.)
13. Add a section for the next release {0.X.Y+1} to doc/whats-new.rst:
11. Add a section for the next release {YYYY.MM.X+1} to doc/whats-new.rst:
```rst
.. _whats-new.0.X.Y+1:
.. _whats-new.YYYY.MM.X+1:
v0.X.Y+1 (unreleased)
vYYYY.MM.X+1 (unreleased)
---------------------
New Features
Expand All @@ -103,17 +85,14 @@ upstream https://github.com/pydata/xarray (push)
~~~~~~~~~~~~~~~~
```
14. Commit your changes and push to main again:
12. Commit your changes and push to main again:
```sh
git commit -am 'New whatsnew section'
git push upstream main
```
You're done pushing to main!

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

## 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
backwards compatible new features, but if a sufficient number of new features
have arrived we will issue a major release even if there are no compatibility
breaks.
Once the project reaches a sufficient level of maturity for a 1.0.0 release, we
intend to follow semantic versioning more strictly.
As of 2022.02.0, we utilize the [CALVER](https://calver.org/) version system.
Specifically, we have adopted the pattern `YYYY.MM.X`, where `YYYY` is a 4-digit
year (e.g. `2022`), `MM` is a 2-digit zero-padded month (e.g. `01` for January), and `X` is the release number (starting at zero at the start of each month and incremented once for each additional release).

0 comments on commit e8d4239

Please sign in to comment.