How to Make a Release

A core developer should use the following steps to create a release X.Y.Z of hdmf.

Note

Since the hdmf 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 CircleCI and Azure Pipelines.
  • You have a GPG signing key.
  • Dependency versions in requirements.txt, requirements-dev.txt, requirements-doc.txt, requirements-min.txt are up-to-date.
  • Legal information and copyright dates are up-to-date in Legal.txt, license.txt, README.rst, docs/source/conf.py, and any other files.
  • Package information in setup.py is up-to-date.
  • README.rst information is up-to-date.
  • The hdmf-common-schema submodule is up-to-date. The version number should be checked manually in case syncing the git submodule does not work as expected.
  • Documentation reflects any new features and changes in HDMF functionality.
  • Documentation builds locally.
  • Documentation builds on ReadTheDocs on the ‘latest’ build.
  • 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.

Setting up environment

  1. First, register for an account on PyPI.

  2. If not already the case, ask to be added as a Package Index Maintainer.

  3. Create a ~/.pypirc file with your login credentials:

    [distutils]
    index-servers =
      pypi
      pypitest
    
    [pypi]
    username=<your-username>
    password=<your-password>
    
    [pypitest]
    repository=https://test.pypi.org/legacy/
    username=<your-username>
    password=<your-password>
    
where <your-username> and <your-password> correspond to your PyPI account.

PyPI: Step-by-step

  1. Make sure that all CI tests are passing on CircleCI and Azure Pipelines.
  2. List all tags sorted by version
$ git tag -l | sort -V
  1. Choose the next release version number
$ release=X.Y.Z

Warning

To ensure the packages are uploaded on PyPI, tags must match this regular expression: ^[0-9]+(\.[0-9]+)*(\.post[0-9]+)?$.

  1. Download latest sources
$ cd /tmp && git clone --recurse-submodules git@github.com:hdmf-dev/hdmf && cd hdmf
  1. Tag the release
$ git tag --sign -m "hdmf ${release}" ${release} origin/dev

Warning

This step requires a GPG signing key.

  1. Publish the release tag
$ git push origin ${release}

Important

This will trigger builds on each CI services and automatically upload the wheels and source distribution on PyPI.

  1. Check the status of the builds on CircleCI and Azure Pipelines.
  2. Once the builds are completed, check that the distributions are available on PyPI and that a new GitHub release was created.
  3. Create a clean testing environment to test the installation
$ mkvirtualenv hdmf-${release}-install-test && \
  pip install hdmf && \
  python -c "import hdmf; print(hdmf.__version__)"

Note

If the mkvirtualenv command is not available, this means you do not have virtualenvwrapper installed, in that case, you could either install it or directly use virtualenv or venv.

  1. Cleanup
$ deactivate  && \
  rm -rf dist/* && \
  rmvirtualenv hdmf-${release}-install-test

Conda: Step-by-step

Warning

Publishing on conda requires you to have corresponding package version uploaded on PyPI. So you have to do the PyPI and Github release before you do the conda release.

In order to release a new version on conda-forge, follow the steps below:

  1. Choose the next release version number (that matches with the pypi version that you already published)
$ release=X.Y.Z
  1. Fork hdmf-feedstock
First step is to fork hdmf-feedstock repository. This is the recommended best practice by conda.
  1. Clone forked feedstock

    Fill the YOURGITHUBUSER part.

    $ cd /tmp && git clone https://github.com/YOURGITHUBUSER/hdmf-feedstock.git
    
  2. Download corresponding source for the release version

$ cd /tmp && \
  wget https://github.com/hdmf-dev/hdmf/releases/download/$release/hdmf-$release.tar.gz
  1. Create a new branch

    $ cd hdmf-feedstock && \
      git checkout -b $release
    
  2. Modify meta.yaml

    Update the version string and sha256.

    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/hdmf-$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/hdmf-$release.tar.gz | awk '{print $2}')
    $ sed -i -- "3s/.*/{$ set sha256 = \"$sha\" %}/" recipe/meta.yaml
    
If requirements-min.txt was changed, the changes should be reflected in the requirements/run list.
  1. Push the changes

    $ git push origin $release
    
  2. Create a Pull Request

    Create a pull request against the main repository. If the tests pass, merge the PR, and a new release will be published on Anaconda cloud.