# Developers Guide

## Team

- Kai Mühlbauer

- Stephan Hoyer

## Contributors

- Aleksandar Jelenak

- Bas Couwenberg.

- Brett Naul

- Dion Häfner

- Drew Parsons

- Frédéric Laliberté

- Ghislain Vaillant

- Lion Krischer

- Mark Harfouche

- Martin Raspaud

- Pierre Augier

- Ryan Grout

- Scott Henderson

- 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` (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:

- 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)

previous

h5netcdf.legacyapi.Variable

next

Change Log