Skip to content

How to make a release

Jump to bottom
Stefan Appelhoff edited this page Dec 7, 2023 · 37 revisions

Table of contents

Versioning of MNE-BIDS

MNE-BIDS loosely follows semver:

  • Versions consist of strings like 0.11.1, where the components refer to major.minor.patch versions.
  • For versions where the patch is 0, that component is omitted from the version, that is, 0.11.0 is simplified to 0.11.
  • On GitHub releases, the versions are prepended with a v, that is, 0.11 becomes v0.11. On PyPI, Conda-Forge, and for the __version__ variable in __init__.py this is not the case.
  • While we are in the 0 major version, breaking changes are permitted without incrementing the major version (i.e., a minor release is okay).
  • The MNE-BIDS documentation is version-tracked only for major and minor versions. Patch releases get merged into the documentation version of the corresponding major/minor version. For example, for 0.11.1, no new documentation version is created, but the documentation version of 0.11 is updated
    • Note that this means that doc version updates from e.g., 0.11.1 will also occur in the doc version for 0.12

Before making a release

NOTE

The instructions below all refer to a major or minor release. For a patch release, see How to make a patch release.

  • Make sure all milestones are achieved (closed) or migrated to the next version
  • Also check the projects page for open issues and either finish or migrate them to the next version
  • Make sure the CI passes on main
    • If you are using the "main"/"dev" version for external packages in your CIs (e.g., mne, bids-validator), you will need to adjust this to point to a specific commit or stable version.
    • Else this will lead to problems in the future, when an old release of mne-bids will still use the main version in the CIs, for building the docs, etc.
    • Files to look at are:
      • .github/workflows/unit_tests.yml
      • circleci/config.yml
      • pyproject.toml

Start a new PR, preparing a release

  • add new lines to the doc/_static/versions.json file to reflect a new release
  • edit whats_new.rst according to the schema that was used for previous releases (changelog, bug, api, code health, ...)
    • for releases, we also add an authors section (this is not present for the "current" section)
    • run git shortlog v0.1..HEAD --summary --numbered --email (replace the version tag to the most recent version) to find contributor names for this release
    • if necessary, update the .mailmap file at this point, so that each author/contributor has one identity (name+email), instead of several
    • 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 relevant section of the version-to-be-released's changelog
  • merge the PR into main using SQUASH and merge ... the release PR should be a single commit

Test the software

  • from your PR branch first run pip install -e .[dev] and then make and assert that all runs without errors
    • inspect the built docs for errors

Prepare for pushing to PyPI

  • run pip install -U build twine to prepare for building the dist
  • run python -m build ... build the dist and wheel
  • Upload to test-pypi:
    • upload to test-pypi twine upload --repository-url https://test.pypi.org/legacy/ dist/*
    • inspect it
    • test it via pip install --extra-index-url=https://test.pypi.org/simple/ mne-bids
      • 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

Prepare stable docs

  • from main, branch off a maint/0.2 branch (or whatever the version-to-be-released is)
  • push the maint/0.2 branch to upstream
  • build the docs from this maint/0.2 branch (everything should work because we checked it in the steps before), using make build-doc, resulting in contents in the doc/_build/html folder.
  • on the gh-pages branch:
    • add a new folder v0.2 where you put the contents of doc/_build/html
    • replace the contents of the stable folder with the contents of doc/_build/html
    • this is effectively duplicating the doc/_build/html contents, but that's okay, and we want that (see wiki entry on docs)
    • push all of this, so that it's upstream in mne-tools's gh-pages branch

Push to PyPI (needs admin access)

  • run twine upload dist/* to upload to pypi

Finalize the release

  • make an annotated tag for the version: git tag -a -m "v0.2" v0.2 upstream/main
  • push the tag to GitHub: git push upstream v0.2
  • use the GitHub feature "Releases" to make a new release on the newly pushed tag, e.g. v0.2. Use v0.2 for all fields (version number, name, description), otherwise they get auto-populated with annoying things.
  • close milestone and project on GitHub ... open new milestone and project for next version, in case you did not do so already
  • move the newest changelog to whats_new_previous_releases.rst and edit whats_new.rst to reflect a new development cycle (it's "unreleased", and the subheadings won't have items)

How to make a patch release

Please be familiar with the usual release protocol (see above) before proceeding.

  • First, checkout the maint/0.2 (or whatever version was most recently released) branch
  • Then use git cherry-pick <commit> to add commits from main to maint/0.2
  • Make sure that you only add commits that are bug fixes
  • Make sure that the commits you add do not change dependencies or other infrastructure requirements
  • You most likely will need to resolve some merge conflicts, in particular with regards to the changelog
    • make a new section in the changelog (whats_new.rst): Version 0.2.1 (YYYY-MM-DD)
    • list all new changes in that section, and add the following intro sentence:

    • Version 0.2.1 is a patch release, all changes are listed below. For more complete information on the 0.2 version, see changelog below.

Once you have added all commits that you want to release to the branch, continue as follows:

  • From the maint/0.2 (for example) branch, make an annotated tag for the version: git tag -a -m "v0.2.1" v0.2.1 upstream/main
  • Push the tag upstream: git push upstream v0.2.1
  • Build the documentation and push the built docs to the v0.2 and stable folders on the gh-pages branch
  • Build the distribution and push it to PyPI; also update conda-forge later (see more info below)
  • Make a GitHub release of the version, using the new tag

Updating the conda package

The conda-forge channel includes a conda package of mne-bids. A dedicated git repository, which is called a feedstock in conda-forge terms, contains the recipe describing all steps required to build and test the package; it can be found at recipe/meta.yaml.

Whenever a new version of mne-bids is published on PyPI, a conda-forge bot will automatically open a Pull Request (PR) to update the following parts of meta.yaml:

  • version number, e.g. {% set version = "0.3" %}

  • SHA256 hash of the source archive, e.g. sha256: 187add419562e3607c161eaf04971863c134febad2e70313260a58238e519ba5

  • build number is reset to zero: number: 0

Before merging, please check whether the dependencies of mne-bids have changed. If that's the case, you have two options, described below.

Updating dependencies via GitHub browser interface

This is the most straightforward option:

  • using your web browser, navigate to the bot's branch of mne-bids-feedstock it wants to merge (you can simply follow the link on top of the respective PR page)
  • navigate to recipe/meta.yaml, and click on the edit button
  • adjust the package dependencies in the requirements: run section
  • commit the changes directly to the bot's branch (all recipe maintainers have write access)
  • wait for CI to successfully finish and merge the PR

Updating dependencies locally

If you prefer not to use the web interface:

  • fork the bot's fork of the mne-bids-feedstock repository (or add it as a remote)
  • checkout the respective branch (it's typically called vXY, where XY is the version number, e.g., v0.3)
  • adjust the package dependencies in the requirements: run section of recipe/meta.yaml
  • commit and push the changes to the bot's branch
  • wait for CI to successfully finish and merge the PR

After the changes have been merged and the package is built, it may take up to 60 minutes to propagate across all conda-forge mirrors.

Other changes to the recipe

Of course, changes to the recipe are not bound to a new upstream release. You may change any part of the recipe at any time.

It is important to always work on a branch of your fork of mne-bids-feedstock. Even if you are a recipe maintainer (which provides you with write access to the mne-bids-feedstock repository), do not create branches on that repository directly (or, even worse, commit to its master branch).

  • increase the build number
  • open a a PR
  • rerender the feedstock by posting @conda-forge-admin, please rerender as a comment to the PR
  • merge the PR once all tests have passed

Again, it may take up to 60 minutes for the new package to appear on all mirrors.

See the conda-forge documentation for additional information.

Clone this wiki locally