RELEASE_PROCEDURE.md

Release procedure

Required accounts and admin privileges

• pip: https://pypi.org/project/pyam-iamc/ and https://test.pypi.org/project/pyam-iamc/
• conda: https://github.com/conda-forge/pyam-feedstock/
• rtd: https://readthedocs.org/projects/pyam-iamc/

Steps for publishing a new release

1. Make a release candidate branch (e.g., release/rc_v<release version>) and pull request it into main with the following updates:
   1. If it's the first release in a new year, search for Copyright 2017 and bump the year
   2. Deprecate any stated portion of the API (you can find them by searching the code base for "deprecate")
   3. Update RELEASE_NOTES.md (see the examples of previous releases)
      • replace "# Next Release" with "# Release v"
      • for this new release, add a "## Highlights" section with the most important updates & changes
      • add a new heading "## Individual Updates" before the PR listing
2. Confirm that the PR passes all tests and checks
3. Tag the release number: git tag v<release version>, e.g., git tag v1.2.0
   • THIS IS NOT THE TAGGED COMMIT WE WILL DISTRIBUTE, IT IS ONLY FOR TESTING
   • DO NOT PUSH THIS TAG TO UPSTREAM
4. Run make publish-on-testpypi
   • this should "just work" - if it does not, fix any issues, retag (git tag -d then git tag), and try again
5. Once successful, delete the tag, and merge the candidate PR into main on Github
6. Switch to the now-updated main branch: git checkout main and git pull upstream main
7. Tag the release number: git tag v<release version>, e.g., git tag v1.2.0
   • versioneer automatically updates the version number based on the tag
   • this is now the official tagged commit
8. Push the tag upstream: git push upstream --tags
9. Run make publish-on-pypi
   • this will make wheels that allow pyam to be installed via pip install
   • check that the new version is available at https://pypi.org/project/pyam-iamc/
10. Make a new release on Github
    • make sure that you choose the tag name defined above
    • copy the release summary from RELEASE_NOTES.md into the description box
11. Update on conda-forge
    • a PR should automatically be opened by the bot after the Github release
    • confirm that any new depedencies are added there
    • merge the PR
    • check that the new version is available at https://anaconda.org/conda-forge/pyam
12. Confirm that the doc pages are updated on https://pyam-iamc.readthedocs.io/
    • both the latest and the stable versions point to the new release
    • the new release has been added to the list of available versions
13. Add a new line "# Next Release" at the top of RELEASE_NOTES.md and commit to main
14. Announce it on our mailing list: https://groups.io/g/pyam
    • again, copy the rendered HTML from the Github release directly in the email

And that's it! Whew...