release 1.3

[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 -m "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 mne/_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. Commit and push this to the appropriate maint branch.

package for PyPI

• empty the dist/ folder (in case you have wheels left from prior releases).
• 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). You can get the sha sum from sha256 dist/mne-X.Y.Z.tar.gz (with X.Y.Z subsituted for the real version number, of course)

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

Close milestone

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

Do all the deprecations

• do something like git grep deprecat, find all the deprecations that are slated to be removed in the now-current dev version, and open a PR to remove them.

stuff we no longer do:

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

[larsoner]

Feel free to merge and continue whenever you think it makes sense, thanks for pushing this out @drammock !

[drammock]

hey @moritz-gerster and @dissagaliyeva; I noticed that in #11245 you credited Jennifer Behnke, Hakimeh Aslsardroud, and Pavel Navratil as contributors. But they weren't listed as co-authors on any commits in that PR, so in order for them to get credit as authors in the next release, I need to create an empty commit with them as commit authors. Which means I need (ideally github-associated) email addresses for each of them. Can you provide those? You can email to me privately if you don't want to post them publicly here. My email address is in the sidebar of my homepage (https://dan.mccloy.info)

[moritz-gerster]

Sure, @drammock, I will send them to you via e-mail as soon as I get them!

[drammock]

@moritz-gerster I ended up using fake @localhost email addresses for them, because I can't really delay the release much longer.