How to make a release

[Inspired by mne-bids]

Before making a release:

• Make sure all milestones are achieved or migrated to the next version
• Make sure the CI passes on master

Start a new PR, preparing a release:

• edit version in __init__.py ... we use X.X, ... and X.X.dev0 for development versions
• edit whats_new.rst according to the schema that was used for previous releases (changelog, bug, api)
  • for releases, we also add an authors section (this is not present for the "current" section)
  • run git shortlog v0.1..HEAD --summary --numbered (replace the version tag to the most recent version) to find contributor names for this release
  • manually add authors who have done a lot of work (reviewing, advising, ...) but don't show up in the shortlog because they did not submit PRs
  • Then order the names alphabetically and add to the last section of the version-to-be-released's changelog
• merge the PR into master using SQUASH and merge ... the release PR should be a single commit

Test the software:

• from your PR branch first run pip install -e . and then make and make build-doc and assert that all runs without errors
  • inspect the built docs for errors

Prepare for pushing to pypi:

• run pip install -U setuptools wheel twine to prepare for building the dist
• run python setup.py sdist bdist_wheel ... build the dist
• Upload to test-pypi:
  • upload to test-pypi twine upload --repository-url https://test.pypi.org/legacy/ dist/*
  • inspect it
  • test it via pip install --index-url https://test.pypi.org/simple/ pyglmnet
    • you might want to do this install in a separate environment
    • the -vvv flag and --no-cache-dir flag might come in handy if it is not working as expected

Prepare stable docs:

• from master, branch off a maint/0.2 branch (or whatever the version-to-be-released is)
• push the maint/0.2 branch to upstream
• Build the docs by running the command $ make install in the doc/ folder of the maint/0.2 branch or the master (they should both point to the same commit at this point)

Push to pypi (needs admin access):

• run twine upload dist/* to upload to pypi

Finalize the release:

• make an annotated tag for the version: git tag -a -m "v0.2" v0.2 upstream/master
• push the tag to GitHub: git push upstream v0.2
• use the GitHub feature "Releases" to make a new release on the newly pushed tag, e.g. v0.2. Use v0.2 for all fields (version number, name, description), otherwise they get auto-populated with annoying things.
• close milestone on GitHub
• add .dev0 to the version in __init__.py
• add a current section to the changelog whats_new.rst