Developers Guide

Team

• Kai Mühlbauer

• Stephan Hoyer

Contributors

• Aleksandar Jelenak

• Bas Couwenberg.

• Brett Naul

• David Huard

• Dion Häfner

• Drew Parsons

• Ezequiel Cimadevilla Alvarez

• Frédéric Laliberté

• Ghislain Vaillant

• John Readey

• Jonas Grönberg

• Kurt Schwehr

• Lion Krischer

• Mark Harfouche

• Martin Raspaud

• Pierre Augier

• Rickard Holmberg

• Ryan Grout

• Scott Henderson

• Thomas Kluyver

• Tom Augspurger

If you are interested to contribute, just let us know by creating an issue or pull request on github.

Contribution Guidelines

• New features and changes should be added via Pull Requests from forks for contributors as well as maintainers.

• Pull Requests should have at least one approval (once the maintainer count has increased).

• Self merges without approval are allowed for repository maintenance, hotfixes and if the code changes do not affect functionality.

• Directly pushing to the repository main branch should only be used as a last resort.

• Releases should be introduced via Pull Request and approved. Exception: Patch release after hotfix.

Continuous Integration

h5netcdf uses GitHub Actions for Continuous Integration (CI). On every push to a repository branch or a PullRequest branch several checks are performed:

• Lint and style checks (ruff, black)

• Unit tests with latest h5py3 (and Python versions) facilitating GitHub Ubuntu worker

• Documentation build, artifacts are made available to download

• On release, source-tarball and universal wheel is uploaded to PyPI and documentation is made available on h5netcdf GitHub Pages

Documentation

The documentation, located in doc-folder, can be created using sphinx-doc and the sphinx-book_theme:

$ cd doc
$ make html

The rendered documentation is then available in the subfolder _build.

Due to the history several documents, eg. README.rst and CHANGELOG.rst, are located in the project’s root folder. They are linked into the documentation via .. include-directive. Links and cross-references originating from these files should be hardcoded to maintain operation also in non-rendered format.

Release Workflow

1. Create release commit (can be done per PullRequest for more visibility)

   • versioning is done via setuptools_scm

   • update CHANGELOG.rst if necessary

   • add/update sections to README.rst (or documentation) if necessary

   • check all needed dependencies are listed in setup.py

2. Create release

   • draft new github release

   • tag version (eg v1.2.0) @ Target: main

   • set release title (eg. release 1.2.0)

   • add release description (eg. bugfix-release), tbd.

This will start the CI workflow once again. The workflow creates sdist and universal wheel and uploads it to PyPI.

References

This section contains links to material how netCDF4 facilitates HDF5.

Some valuable links on dimension scales:

• HDF5 Dimension Scales

• HDF5 Dimension Scales Part 2

• HDF5 Dimension Scales Part 3

• NetCDF-4 Dimensions and HDF5 Dimension Scales

• NetCDF-4 use of dimension scales

Other resources

• NetCDF-4 performance

• String **NULLTERM** vs. **NULLPAD**

netCDF4-python quirks:

• _Netcdf4Dimid gets attached to all data variables if a 2D coordinate variable is created and any variable is written/file is reopened for append, see issue 1104

• unlimited variable dimensions are reported as current size of the dimension scale, even if the variable’s underlying DATASPACE dimension is smaller (eg. 0)