How to make a release

Before making 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~~ (no longer building optimization examples for release docs)
update any URLs containing dev with stable in README.rst.
Update hnn-core/doc/_templates/navbar.html to include a link the version being released

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

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/

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

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