Software Process

Continuous Integration

HDMF is tested against Ubuntu, macOS, and Windows operating systems. The project has both unit and integration tests.

Each time a PR is published or updated, the project is built, packaged, and tested on all supported operating systems and python distributions. That way, as a contributor, you know if you introduced regressions or coding style inconsistencies.

There are badges in the README file which shows the current condition of the dev branch.

Coverage

Code coverage is computed and reported using the coverage tool. There are two coverage-related badges in the README file. One shows the status of the GitHub Action workflow which runs the coverage tool and uploads the report to codecov, and the other badge shows the percentage coverage reported from codecov. A detailed report can be found on codecov, which shows line by line which lines are covered by the tests.

Requirement Specifications

There are 4 kinds of requirements specification in HDMF.

The first one is the requirements-min.txt file, which lists the package dependencies and their minimum versions for installing HDMF. These dependencies are read by setup.py into the install_requires key, with the adjustment that the ‘==’ listed in requirements-min.txt are replaced with ‘>=’ to reflect that they are minimum versions.

The second one is requirements.txt which contain a list of pinned (concrete) dependencies to reproduce an entire development environment to use HDMF.

The third one is requirements-dev.txt which contain a list of pinned (concrete) dependencies to reproduce an entire development environment to use HDMF, run HDMF tests, check code style, compute coverage, and create test environments.

The final one is requirements-doc.txt which contain a list of dependencies to generate the documentation for HDMF. Both this file and requirements.txt are used by ReadTheDocs to initialize the local environment for Sphinx to run.

In order to check the status of the required packages, requires.io is used to create a badge on the project README. If all the required packages are up to date, a green badge appears.

If some of the packages are outdated, see How to Update Requirements Files.

Versioning and Releasing

HDMF uses versioneer for versioning source and wheel distributions. Versioneer creates a semi-unique release name for the wheels that are created. It requires a version control system (git in HDMF’s case) to generate a release name. After all the tests pass, CircleCI creates both a wheel (*.whl) and source distribution (*.tar.gz) for Python 3 and uploads them back to GitHub as a release. Versioneer makes it possible to get the source distribution from GitHub and create wheels directly without having to use a version control system because it hardcodes versions in the source distribution.

It is important to note that GitHub automatically generates source code archives in .zip and .tar.gz formats and attaches those files to all releases as an asset. These files currently do not contain the submodules within HDMF and thus do not serve as a complete installation. For a complete source code archive, use the source distribution generated by CircleCI, typically named hdmf-{version}.tar.gz.