Skip to content

How to make a major or minor release

Jump to bottom Edit New page
Eric Larson edited this page Aug 15, 2023 · 43 revisions

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, should be the previous "Archive X-1.Y" commit
$ 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...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 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.

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" (example commit), 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). Commit and push this change (git push upstream maint/X.Y).

  • Edit setup.py to have the following lines at the top:

    if "SETUPTOOLS_SCM_PRETEND_VERSION" not in os.environ:
    os.environ["SETUPTOOLS_SCM_PRETEND_VERSION"] = "X.Y.Z"

    This forces the version to stay fixed even though we will occasionally (and right now) push a commit to 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/X-1.Y branch with [ci skip] in the commit message.

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 changelog (again)

  • 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 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

Close milestone

Do all the deprecations

  • do something like git grep deprecat -- ':!*.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.

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
Add a custom footer
Add a custom sidebar
Clone this wiki locally