HOW_TO_RELEASE.md

How to issue a regionmask release in n easy steps

Time required: about an hour.

These instructions assume that upstream refers to the main repository (https://github.com/regionmask/regionmask).

1. Ensure your main branch is synced to upstream:

   git switch main
   git pull upstream main

2. Maybe write a release summary: ~50 words describing the high level features.
3. 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.
4. Open a PR with the release summary and what's new changes.
5. After merging, again ensure your main branch is synced to upstream:

   git pull upstream main

6. Check that the tests and ReadTheDocs build is passing!
7. Issue the release on GitHub. Click on "Draft a new release" at https://github.com/regionmask/regionmask/releases. Type in the version number (with a "v") and paste the release summary in the notes. This should
   • upload a new version to pypi
   • create a new version on zenodo
   • open a PR at https://github.com/conda-forge/regionmask-feedstock to create a new version on conda-forge (might take some hours). Make sure to double check the required versions.
8. Add a section for the next release to CHANGELOG.rst:

   .. _changelog.0.X.Y:
   
   v0.X.Y (unreleased)
   --------------------
   
   Breaking Changes
   ~~~~~~~~~~~~~~~~
   
   Enhancements
   ~~~~~~~~~~~~
   
   Deprecations
   ~~~~~~~~~~~~
   
   New regions
   ~~~~~~~~~~~
   
   Bug Fixes
   ~~~~~~~~~
   
   Docs
   ~~~~
   
   Internal Changes
   ~~~~~~~~~~~~~~~~
   

9. Update zenodo link.
10. Commit your changes and push to main again:

    git co -b "new_changelog_section"
    git commit -am 'New changelog section'
    git push origin HEAD

11. Check if the new docs get built. Login to https://readthedocs.org/projects/regionmask/versions/.
12. Release regionmask on conda - also update the requirements in meta.yaml https://github.com/conda-forge/regionmask-feedstock

Credit

These instructions were copied from xarray.

---

Manual upload to pypi - deprecated

1. Tag the release:

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

2. Ensure the dependencies for building are installed:

   mamba update pip
   python -m pip install build twine

3. Build source and binary wheels for PyPI:

   git clean -xdfn  # This removes any untracked files! - Dry run -

   For real

   git clean -xdf  # This removes any untracked files!
   git status # check for tracked files
   git restore -SW .  # This removes any tracked changes!
   python -m build

4. Use twine to check the package build:

   twine check --strict dist/regionmask*

5. Use twine to register and upload the release on PyPI. Be careful, you can't take this back!

   twine upload dist/*

   You will need to be listed as a package owner at https://pypi.python.org/pypi/regionmask for this to work.
6. Push your changes to main:

   git push upstream main
   git push upstream --tags