From 03a7c052eb8ccc4cccaa2e20748dffae9d2a5c4b Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Sun, 30 Jan 2022 20:52:54 -0800 Subject: [PATCH] update release steps - no more stable branch - switch to calver --- HOW_TO_RELEASE.md | 62 ++++++++++++++--------------------------------- 1 file changed, 18 insertions(+), 44 deletions(-) diff --git a/HOW_TO_RELEASE.md b/HOW_TO_RELEASE.md index 33a4fb9bfc3..893a6d77168 100644 --- a/HOW_TO_RELEASE.md +++ b/HOW_TO_RELEASE.md @@ -18,12 +18,7 @@ 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, /' ``` @@ -31,52 +26,39 @@ upstream https://github.com/pydata/xarray (push) ```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 . 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 @@ -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 - 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 xarray@googlegroups.com. For major/feature releases, I will email a broader list (no more than once every 3-6 months): - pydata@googlegroups.com @@ -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).