Skip to content

How to make a release

Jump to bottom
Stefan Appelhoff edited this page Mar 26, 2021 · 49 revisions

Table of contents

Before making a 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
      • requirements.txt
      • /doc/requirements.txt
      • and the environment.yml on the gh-pages branch, which is used for the BINDER compatibility. see sphinx-gallery-issue628 and issue comment on mne-bids PR #4333 ... please design the environment.yml file such that it will work with the most recent stable version of MNE-BIDS after the release you are currently preparing.

Start a new PR, preparing a release

  • edit version in __init__.py ... we use X.Y, ... and X.Y.dev0 for development versions
  • add a line to doc/_templates/navbar.html reflecting a new release. E.g., if the release is 0.2, add the following line in the proper place: <li><a href="https://mne.tools/mne-bids/v0.2/index.html">v0.2</a></li>
  • edit whats_new.rst according to the schema that was used for previous releases (changelog, bug, api)
    • 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 last 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 . and then make and make build-doc and assert that all runs without errors
    • inspect the built docs for errors

Prepare for pushing to PyPI

  • run pip install -U setuptools wheel twine to prepare for building the dist
  • run python setup.py sdist bdist_wheel ... build the dist
  • 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 --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-docs, 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
  • increment the version in __init__.py and append .dev0. E.g., after releasing v0.2, the __version__ variable in __init__.py should be 0.2. Now after the release it should be changed to 0.3.dev0 because this is the development version of v0.3
  • add a current section to the changelog whats_new.rst

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