Release 1.2

[drammock]

update pinned website theme commit

Detailed instructions here but the basic steps are:

• Using an editable install of the website theme, build docs locally against current HEAD of the theme, and find the newest commit that still looks good with our site
• update the website theme pin in our requirements_doc.txt.

fix milestone issues / pending PRs.

• Fix other milestone issues and PRs.
• Check dev-docs build to make sure they look OK, and check CircleCI to make sure the most recent build was green. NOTE: If any PRs were merged since the most recent overnight run of build-dev-docs, you may need to run a [circle deploy] to get the docs up-to-date with the desired state of the code at release time.
• Manually update counts in docs/cited.rst

update website repo (mne-tools/mne-tools.github.io)

• Squash all website commits since the last release:

  $ git reset --soft 3c7b371fc5  # find the appropriate hash
  $ git commit -am "X.Y Squash"
  $ git push origin main -f

• Manually archive the current version and link the new version to stable (see this example PR):

  $ cp -a stable X.W  # the previous stable version
  $ git add X.W/*
  $ git commit -am "Archive X.W"
  $ git push origin main

update changelog

• Generate author list (note there is a version number in this command, be sure to update it):

  git shortlog -s --group=author --group=trailer:co-authored-by HEAD...v0.21.0 | sed "s/^ *[0-9]* *\t*/* /"

  Using the --group option in git shortlog is important to capture "co-authored-by", and requires git 2.29+ (if your git is older than that, there is an official git PPA for debian-like systems).

• Add missing authors. Add anyone missing from the author list (e.g., first-time contributors who did not (co)author any commits but contributed during review/iteration). NOTE: make sure things are clean / not in process before doing this:

  git commit --allow-empty --author="First last <use.git.log.pipe.grep.name@to.find.email.com>" -m "Empty commit for credit"

• Ensure full names for all authors. If there are authors without full names, check if they already exist in doc/changes/names.inc; if so, update .mailmap to map their full name to their alias. If they're not yet in doc/changes/names.inc, use the --email option in the git shortlog command above to get their email address and ping them to ask if they want to provide a full name and URL; when they do, update .mailmap and doc/changes/names.inc.

• Deduplicate authors. Check the list for duplicate names (e.g., Alex Gramfort and Alexandre Gramfort) and deduplicate by adding more .mailmap entries.

• Add "authors" section to doc/changes/latest.inc. Rerun the git shortlog command above to generate the final list. Look at previous files (doc/changes/1.0.inc) for formatting example. Run make codespell and add any violating names to ignore_words.txt.

• Highlight new contributors. Manually add + symbols next to new contributors in the list, and make sure their entries are properly formatted. Some users will not be associated with a given pull request / have a :newcontrib: entry -- git grep <name> can tell you if it's their first time contributing.

• Update changelog title and shortcut. At the top of doc/changes/latest.inc Change "Current" to "Version X.Y.Z (YYYY-MM-DD)", replacing X.Y.Z with the release version being prepared, and YYYY-MM-DD with the release date. Also change .. _current:: to .. _changes_X_Y_Z:.

• Rename changelog file. git mv doc/changes/latest.inc doc/changes/X.Y.inc

• Update doc/whats_new.rst to point to X.Y.inc instead of latest.inc

update the version string

• In mne-python, update doc/_static/versions.json to add an entry and updated stable/devel.
• Update the supported version table in SECURITY.md
• In _version.py change X.Y.dev0 to X.Y.0
• In .circleci/config.yml bump the version in "maint/X.Y"
• In tools/circleci_download.sh bump the version in "$CIRCLE_BRANCH" == "maint/X.Y"

update codemeta and citation

• Edit tools/generate_codemeta.py to update the compound_surnames variable (if needed, based on new contributors from the changelog).
• Then run cd tools/ && python generate_codemeta.py to update the codemeta metadata and CITATION.cff files for this release, and stage them: git add codemeta.json CITATION.cff

commit and push

• If you have been committing along the way, squash your commits. Otherwise commit all changes made so far
• Push to upstream main (or merge in your "prep for release" PR)

make a release tag

• Use the GitHub feature "Releases" to make a new release. Use vX.Y.Z for all fields (version number, name, description), otherwise they get auto-populated with annoying things. The "target" of the release should be main.

create new stable branch

• Create and check out a new branch maint/X.Y
• Edit .circleci/config.yml to change names "build_docs_main" to "build_docs_stable" (example commit), and change the workflow name from "main" to "stable". Commit and push this change (git push upstream maint/X.Y).
• Check out the previous stable branch (maint/X.Y-1 or maint/X-1.Y) and remove the "stable" workflow from .circleci/config.yml

package for PyPI

• create wheel and source dist. python setup.py sdist bdist_wheel
• test the wheel.

  $ pip uninstall mne
  $ pip install dist/mne-*-py3-none-any.whl
  # [output omitted]
  $ pushd ~; python -c "import mne; mne.sys_info()" | grep mne; popd

• upload to TestPyPI. twine upload dist/* --repository testpypi --verbose
• upload to Real PyPI. twine upload dist/* --verbose

package for Conda

• Update conda-forge/mne-feedstock. This will eventually happen automatically (example here, but you can speed things up by opening a manual pull request. At a minimum, you must update version and sha256 in recipe/meta.yaml; other additions will depend on what has changed for the project (e.g., minimum dependency versions).

update version numbers (again)

• Change the version number in mne/_version.py to next dev version, e.g. X.Y+1.dev0
• Restore latest.inc.

  cp doc/changes/latest.inc.template doc/changes/latest.inc
  git add doc/changes/latest.inc

  Now edit the version number in it, and add it (back) to the list of includes in doc/whats_new.py
• Commit and push these changes to main

update MNE Installers

• Update MNE Installers. Here is an example PR
• Update documentation links to installers. Change button links doc/install/installers.rst to point to the new installer files. Make sure to update links for all 3 platforms. Push this change to both maint/X.Y and main, with commit message [circle deploy].

announce the release

• email mne_analysis@nmr.mgh.harvard.edu
• add a post in the Announcements category on Discourse
• announce on Discord?

package for Debian

• Check out the repo.

  # make sure your ssh key + ssh config is configured for the remote repo, then:
  git clone ssh://git.debian.org/git/debian-med/python-mne.git
  cd python-mne
  uscan --verbose --force-download
  git import-orig --pristine-tar ../mne-python_XXX.orig.tar.gz
  dch -i  # update changelog + eventually copyright is need files added

- [ ] *Remove previous builds if they exist.*
  ```bash
  rm -r build
  rm mne/html/bootstrap.min.js
  rm debian/python-mne*
  rm -r debian/python-mne

• Build the package. git-buildpackage --git-verbose --git-ignore-new -uc -us --git-tag
• If the build fails: make modifications, commit the patch and try building again: dpkg-source --commit
• Check conformity to debian build rules.

  lintian -i python-mne*.changes
  cme fix dpkg-copyright  # check formatting of copyright file

• Commit the release. git push

Close milestone

• https://github.com/mne-tools/mne-python/milestones

[drammock]

• https://github.com/mne-tools/mne-python/releases/tag/v1.2.0
• https://pypi.org/project/mne/1.2.0/
• bump to 1.2 conda-forge/mne-feedstock#108
• bump to v1.2 mne-installers#153