How to Make a Release
A core developer should use the following steps to create a release X.Y.Z
of pynwb.
Note
Since the pynwb wheels do not include compiled code, they are considered pure and could be generated on any supported platform.
That said, considering the instructions below have been tested on a Linux system, they may have to be adapted to work on macOS or Windows.
Prerequisites
All CI tests are passing on GitHub Actions.
You have a GPG signing key.
Release notes have been prepared.
An appropriate new version number has been selected.
Documentation conventions
The commands reported below should be evaluated in the same terminal session.
Commands to evaluate starts with a dollar sign. For example:
$ echo "Hello"
Hello
means that echo "Hello"
should be copied and evaluated in the terminal.
Make pre-release pull request on GitHub: Step-by-step
Create a new branch locally or on GitHub. Update the
CHANGELOG.md
with the release date.
$ git checkout -b release-X.Y.Z
2. Create a pull request for the new release branch, then append the URL with: “&template=release.md”.
For example, https://github.com/NeurodataWithoutBorders/pynwb/compare/dev...release-X.Y.Z?quick_pull=1&template=release.md
Follow the checklist in the template. The checklist covers the following steps in more detail:
Make sure all PRs to be included in this release have been merged to
dev
.Update package versions in
requirements.txt
,requirements-dev.txt
,requirements-opt.txt
,requirements-doc.txt
,requirements-min.txt
,environment-ros3.yml
, andpyproject.toml
.Check legal information and copyright dates in
Legal.txt
,license.txt
,README.rst
,docs/source/conf.py
.Update
pyproject.toml
andREADME.rst
as needed.Update
src/pynwb/nwb-schema
submodule as needed. Check the version number manually to make sure we are using the latest release.Update documentation to reflect new features and changes in PyNWB functionality.
Run tests locally, inspect all warnings and outputs, and try to remove all warnings.
Test documentation builds locally and on the ReadTheDocs project on the “dev” build.
Publish release on PyPI: Step-by-step
Make sure that all CI tests are passing on GitHub Actions.
List all tags sorted by version.
$ git tag -l | sort -V
Choose the next release version number and store it in a variable.
$ release=X.Y.ZWarning
To ensure the packages are uploaded on PyPI, tags must match this regular expression:
^[0-9]+.[0-9]+.[0-9]+$
.
Download the latest sources.
$ cd /tmp && git clone --recurse-submodules git@github.com:NeurodataWithoutBorders/pynwb && cd pynwb
Tag the release.
$ git tag --sign -m "pynwb ${release}" ${release} origin/devWarning
This step requires a GPG signing key.
Publish the release tag.
$ git push origin ${release}Important
This will trigger the “Deploy release” GitHub Actions workflow which will automatically upload the wheels and source distribution to both the PyNWB PyPI project page and a new GitHub release using the nwb-bot account.
Check the status of the builds on GitHub Actions.
Once the builds are completed, check that the distributions are available on PyNWB PyPI project page and that a new GitHub release was created.
Copy the release notes from
CHANGELOG.md
to the newly created GitHub release.Create a clean testing environment to test the installation.
On bash/zsh:
$ python -m venv pynwb-${release}-install-test && \ source pynwb-${release}-install-test/bin/activateOn other shells, see the Python instructions for creating a virtual environment.
Test the installation:
$ pip install pynwb && \ python -c "import pynwb; print(pynwb.__version__)"
Cleanup
On bash/zsh:
$ deactivate && \ rm -rf dist/* && \ rm -rf pynwb-${release}-install-test
Publish release on conda-forge: Step-by-step
Warning
Publishing on conda requires you to have the corresponding package version uploaded on PyPI. So you have to do the PyPI and Github release before you do the conda release.
Note
Conda-forge maintains a bot called “regro-cf-autotick-bot” that regularly monitors PyPI for new releases of
packages that are also on conda-forge. When a new release is detected, usually within 24 hours of publishing
on PyPI, the bot will create a Pull Request with the correct modifications to the version and sha256 values
in meta.yaml
. If the requirements in setup.py
have been changed, then you need to modify the
requirements/run section in meta.yaml
manually to reflect these changes. Once tests pass, merge the PR,
and a new release will be published on Anaconda cloud. This is the easiest way to update the package version
on conda-forge.
In order to release a new version on conda-forge manually, follow the steps below:
Store the release version string (this should match the PyPI version that you already published).
$ release=X.Y.Z
Fork the pynwb-feedstock repository to your GitHub user account.
Clone the forked feedstock to your local filesystem.
Fill the YOURGITHUBUSER part.
$ cd /tmp && git clone https://github.com/YOURGITHUBUSER/pynwb-feedstock.git
Download the corresponding source for the release version.
$ cd /tmp && \ wget https://github.com/NeurodataWithoutBorders/pynwb/releases/download/$release/pynwb-$release.tar.gz
Create a new branch.
$ cd pynwb-feedstock && \ git checkout -b $release
Modify
meta.yaml
.Update the version string (line 2) and sha256 (line 3).
We have to modify the sha and the version string in the
meta.yaml
file.For linux flavors:
$ sed -i "2s/.*/{% set version = \"$release\" %}/" recipe/meta.yaml $ sha=$(openssl sha256 /tmp/pynwb-$release.tar.gz | awk '{print $2}') $ sed -i "3s/.*/{$ set sha256 = \"$sha\" %}/" recipe/meta.yaml
For macOS:
$ sed -i -- "2s/.*/{% set version = \"$release\" %}/" recipe/meta.yaml $ sha=$(openssl sha256 /tmp/pynwb-$release.tar.gz | awk '{print $2}') $ sed -i -- "3s/.*/{$ set sha256 = \"$sha\" %}/" recipe/meta.yaml
If the requirements in
setup.py
have been changed, then modify the requirements/run list in themeta.yaml
file to reflect these changes.
Push the changes to your fork.
$ git push origin $release
Create a Pull Request.
Create a pull request against the main feedstock repository. After the tests pass, merge the PR, and a new release will be published on Anaconda cloud.