How to make a major or minor release

make sure website looks okay and update credit

• We no longer use an upper bound on the theme version, so make sure https://mne.tools/dev looks okay
• Go to our Contributor credit action, and manually Run Workflow if needed to trigger an update of the PR jsons.

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 doc/documentation/cited.rst

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

• Squash all website commits since the last release:

  # find the appropriate hash, should be the previous "Archive X-1.Y" commit
  $ git log | grep -B4 "Archive" | head -5
  commit e9ec0b8f29b791a2a60764976d595923b24eb302
  Author: Eric Larson <[email protected]>
  Date:   Fri Apr 19 09:26:05 2024 -0400
  
      Archive 1.6
  $ git reset --soft e9ec0b8f29b791a2a60764976d595923b24eb302
  $ git commit -am "X.Y Squash"
  $ cp -a stable X.W  # the previous stable version
  $ git add X.W/*
  $ git commit -m "Archive X.W"
  $ git push origin -f 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...v1.6.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 <[email protected]>" -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.

• Use towncrier to turn stubs into a finalized page by running towncrier in the project root:

  towncrier build --yes --version 1.8.0

• Add "authors" section to the bottom of doc/changes/devel.rst and remove towncrier cruft. Rerun the git shortlog command above to generate the final list and remove [bot] authors. Look at previous files (doc/changes/v1.7.rst) 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. Move their entries to the top of each section.

• Add changelog shortcut. At the top of doc/changes/devel.rst add .. _changes_X_Y_Z:.

• Rename changelog file. git mv doc/changes/devel.rst doc/changes/vX.Y.rst

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

update some version strings

• In mne-python, update doc/_static/versions.json to add an entry and updated stable/devel.
• Update the supported version table in SECURITY.md

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 python tools/generate_codemeta.py X.Y.Z 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 GitHub release and 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. This should automatically push to PyPI, which should then automatically trigger a conda-forge update.

create new stable branch

• Create and check out a new branch maint/X.Y based on current upstream/main / tag vX.Y.Z
• Edit .circleci/config.yml to change names "build_docs_main" to "build_docs_stable", change the workflow name from "main" to "stable", change the branch filter from main to /maint\/.*/ (regex), and change the scheduled build time to 4 AM GMT (e.g., this commit, which also contains the following step as well).
• Edit pyproject.toml to have version = "X.Y.Z" instead of "dynamic = ["version"]. Push.
• 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/X-1.Y branch with [ci skip] in the commit message.

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 or by looking at "view hashes" of the release on PyPI like here for 1.7.

update changelog (again)

Back on main:

• Restore devel.rst

  cp doc/changes/devel.rst.template doc/changes/devel.rst
  git add doc/changes/devel.rst

• Add ../changes/devel.rst back into the toctree:: in doc/development/whats_new.rst
• Commit and push to main

update MNE Installers

• Update MNE Installers. Using git grep "1\.6\.[0-9]" for example go through and change to 1.7.0.
• 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 [email protected]
• add a post in the Announcements category on Discourse. After posting, close it (so no replies allowed), then pin it globally.
• unpin the previous release announcement on Discourse.
• announce on Discord (optional)

Close milestone

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

Do all the deprecations

• do something like git grep [Dd]eprecat -- ':!*.js' mne/, find all the deprecations that are slated to be removed in the now-current dev version, and open a PR to remove them.
• be sure to also search for FutureWarning too (hopefully there aren't any DeprecationWarning as we try to stick to FutureWarning only).

Bump minimums

• Look at README.rst and bump minimums to the package releases that existed ~2 years ago at the expected time of next release, e.g., by looking on PyPI release pages. Change the "old" CI job to match.

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