How to make a release

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 and conf.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.3..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
• adjust optimize_evoked.py to plot_optimize_evoked.py and update any URLs containing dev with stable in README.rst.

Test the software:

• from your PR branch first run pip install -e . and then make and make html inside the doc/ folder and assert that all runs without errors
  • inspect the built docs for errors
• merge the PR into master using SQUASH and merge ... the release PR should be a single commit

Prepare for pushing to pypi:

• run pip install -U setuptools wheel twine to prepare for building the dist
• rm -rf hnn-core/hnn_core/mod/x86_64 to delete any pre-built mod files. They should not be distributed
• run python setup.py sdist ... archive the dist for distribution
• Upload to test-pypi:
  • upload to test-pypi twine upload --repository-url https://test.pypi.org/legacy/ dist/*
  • inspect it
  • Run twine check and make sure there are no errors
  • test it via pip install --extra-index-url https://test.pypi.org/simple/ hnn-core[gui]
    • 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
  • check that the README renders correctly on https://test.pypi.org/project/hnn-core/

Prepare stable docs:

• from master, branch off a maint/0.4 branch (or whatever the version-to-be-released is)
• push the maint/0.4 branch to upstream
• Build the docs by running the command $ make html in the doc/ folder of the maint/0.4 branch or the master (they should both point to the same commit at this point). Copy the doc/ directory and its contents to a location outside of the root ~/hnn-core/ directory. The output will be stored in <outside_location>/doc/_build/html
• on the gh-pages branch:
  • add a new folder v0.4 where you put the contents of doc/_build/html with $ cp -r <outside_location>/doc/_build/html/* ~/hnn-core/v0.4/
  • replace the contents of the stable folder with the contents of doc/_build/html with $ cp -r <outside_location>/doc/_build/html/* ~/hnn-core/stable/
  • this is effectively duplicating the doc/_build/html contents, but that's okay, and we want that
  • push all of this, so that it's upstream in jonescompneurolab's gh-pages branch

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.4" v0.4 upstream/master
• push the tag to GitHub: git push upstream v0.4
• use the GitHub feature "Releases" to make a new release on the newly pushed tag, e.g. v0.4. Use v0.4 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 and conf.py
• add a current section to the changelog whats_new.rst
• adjust plot_optimize_evoked.py to optimize_evoked.py and update any URLs containing stable with dev in README.rst