Developers Guide#

Team#

Contributors#

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 (Python 3.9, 3.10, 3.11) 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:

Other resources

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)