mirrors/hdf5
2
0
Fork 0
mirror of https://github.com/HDFGroup/hdf5.git synced 2026-09-25 04:09:44 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updates CONTRIBUTING.md (#5768)

Browse Source 
Updates CONTRIBUTING.md with a comprehensive guide for contributors, modifies a link in README.md, and renames a file path for consistency.
This commit is contained in:
Scot Breitenfeld
2025-09-04 08:05:14 -05:00
committed by GitHub
parent e3012ddc32
commit 6e0b7e5726
4 changed files with 369 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+368 -116
View File
@@ -1,135 +1,387 @@
# How to contribute to HDF5
# How to contribute to HDF5 development
The HDF Group encourages community members to contribute to the HDF5 project. We accept and are very grateful for any contributions,
from minor typos and bug fixes to new features. The HDF Group is committed to work with the code contributors and make contribution
process enjoyable and straightforward.
Welcome to the HDF5 development community! This comprehensive guide covers everything you need to know
about contributing to HDF5, from getting started to submitting your changes.
This document describes guiding principles for the HDF5 code contributors and does not pretend to address any possible
contribution. If in doubt, please do not hesitate to ask us for guidance.
***Note that no contribution may be accepted unless the donor agrees with the HDF Group software license terms
found in the LICENSE file in every branch's top source directory.***
> We will assume that you are familiar with `git` and `GitHub`. If not, you may go through the GitHub tutorial found at
[https://guides.github.com/activities/hello-world/](https://guides.github.com/activities/hello-world/). This tutorial should only take
around 10 minutes.
> [!IMPORTANT]
> No contribution can be accepted unless the contributor agrees to the HDF Group's software license terms,
which can be found in the LICENSE file located in the top source directory of every branch.
## Table of Contents
* <a href="#workflow">Workflow</a>
* <a href="#criteria">Acceptance criteria for a pull request</a>
* <a href="#releasenote">Release Note</a>
* <a href="#checklist">Check List</a>
<h2 id="workflow">Workflow</h2>
The process for contributing code to HDF5 is as follows:
* Open an issue on [HDF5 GitHub](https://github.com/HDFGroup/hdf5/issues).
> This step is ***required*** unless the change is minor (e.g., typo fix).
* Fork the [HDF5](https://github.com/HDFGroup/hdf5) repository.
* Make the desired changes to the HDF5 software.
* New features should always go to _develop_ branch first and later should be merged to the appropriate maintenance branches.
* Bug fixes should go to all appropriate branches (_develop_ and maintenance).
* Build and test your changes. Detailed instructions on building and testing HDF5 can be found in the `INSTALL*` files in the `release_docs` directory.
* Push your changes to GitHub.
* Issue a pull request and address any code formatting and testing issues reported.
Once a pull request is correctly formatted and passes **ALL** CI tests, it will be reviewed and evaluated by The HDF Group developers and HDF5
community members who can approve pull requests. The HDF Group developers will work with you to ensure that the pull request satisfies the acceptance
criteria described in the next section.
<h2 id="workflow">Workflow</h2>
We appreciate every contribution we receive, but we may not accept them all. Those that we *do* satisfy the following criteria:
* **The pull request has a clear purpose** - What does the pull request address? How does it benefit the HDF5 community?
If the pull request does not have a clear purpose and benefits, it will not be accepted.
* **The pull request is documented** - The HDF5 developers must understand not only *what* a change is doing, but *how* it is doing it.
Documenting the code makes it easier for us to understand your patch and maintain the code in the future.
* **The pull request passes HDF5 regression testing** - Any issue fixed or functionality added should be accompanied by the corresponding
tests and pass HDF5 regression testing run by The HDF Group. We do not expect you to perform comprehensive testing across multiple platforms
before we accept the pull request. If the pull request does not pass regression testing after the merge, The HDF Group developers will work
with you on the fixes.
* **The pull request does not compromise the principles behind HDF5** - HDF5 has a 100% commitment to backward compatibility.
* Any file ever created with HDF5 must be readable by any future version of HDF5.
If your patch's purpose is to modify the HDF5 data model or file format,
**please** discuss this with us first. File format changes and features required by those changes can be introduced only in a new major release.
* HDF5 has a commitment to remaining *machine-independent*; data created on one platform/environment/architecture **must** remain readable by HDF5 on any other.
* For binary compatibility, no changes are allowed to public APIs and data structures in the maintenance releases; new APIs can be added.
* **New features are documented** - Any new features should have proper documentation; talk to us if you have any questions.
* **When to Write a Release Note** - Generally, a release note must be written for every change that is made to the code for which
users might see a change in the way the software works. In other words, if a user might see a difference in the way the software works,
a note should be written. By code we mean the text that will be compiled into one of the company's software products. The code includes
configuration changes and changes to tools users might work with to configure and build our software.
* Notes should be added for known problems. Known problems are issues that we know about and have not yet been able to fix.
* Any change made to address a user-reported problem should be described in a release note.
* A release note does not need to be written for changes to the code that users will not see. Here are some examples. If you add a
comment, you do not need to write a release note describing the comment you added. If you rewrite some code to make it read more
clearly and if there is no change in functionality or performance, then you do not need to write a release note. If you change the
process by which user software is made, you may not need to write a release note since the change was not made to the code.
* Users. We have different kinds of users. A release note may be written to be helpful to
application developers and not system administrators. Users who may find the RELEASE.txt file helpful include the following:
application developers, library developers, and system administrators.
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Getting the Source Code](#getting-the-source-code)
- [Building for Development](#building-for-development)
- [Source Code Overview](#source-code-overview)
- [Development Conventions](#development-conventions)
- [Contributing Changes](#contributing-changes)
- [Testing](#testing)
- [Documentation](#documentation)
- [Command-Line Tools](#command-Line-Tools)
- [Checklist for Contributors](#checklist-for-contributors)
- [Getting Help](#getting-help)
<h2 id="releasenote">Release Note</h2>
---
* **Entry Syntax**
The release note entry syntax is shown below.
## Getting Started
```
- Title/Problem
The HDF Group welcomes contributions of all kinds, from fixing typos to adding significant features. We are
dedicated to making the contribution process enjoyable and straightforward.
Problem/Solution
> [!NOTE]
> This guide offers a brief introduction to the HDF5 library and its development procedures. In contrast,
[An Overview of the HDF5 Library Architecture](https://github.com/HDFGroup/arch-doc/blob/main/An_Overview_of_the_HDF5_Library_Architecture.v2.pdf)
aims to provide a comprehensive understanding of the inner workings of the HDF5 library by exploring its fundamental
principles. It covers the systematic, structural, and organized aspects that enable the library to function clearly and
effectively. By reviewing this document, readers can gain insights into the library's architecture and learn how to use
it efficiently. Additionally, it will provide an overview of the various approaches used to simplify the understanding
of the HDF5 library's operations.
---
## Prerequisites
Before you begin, ensure your development machine has:
### Required Tools
* **A C11-compatible C compiler** (MSVC on Windows is supported).
* **A build system:** **CMake** is required.
* **Perl:** Needed to run build and test scripts, even on Windows.
* **Git:** For version control.
- If you are new to Git and GitHub, we encourage you to check out
the [GitHub tutorial](https://guides.github.com/activities/hello-world/), which takes about 10 minutes to complete.
### Recommended Tools
* **clang-format:** For code formatting. The CI system will automatically format pull requests if needed.
* **codespell:** For identifying spelling issues before submission.
* **Doxygen:** For compiling the documentation.
### Optional Components
Depending on which features you want to build or enable:
* A _C++11_-compatible compiler for the C++ wrappers.
* A _Fortran 2003_-compatible compiler for the Fortran wrappers.
* A _Java 8_-compatible compiler for the Java wrappers.
* `flex`/`lex` and `bison`/`yacc` if you want to modify the high-level parsers.
* Development versions of **zlib** and **szip** for compression support.
* An MPI-3 compatible MPI library for parallel HDF5 development.
* `curl` and other components for the read-only S3 VFD.
---
## Getting the Source Code
The HDF5 source code is hosted on GitHub:
```bash
git clone https://github.com/HDFGroup/hdf5.git
cd hdf5
```
* **Entry Elements** - The elements of the entry - title, problem, solution, and signature - are described in more detail in the table
below. Descriptions of the problem and the solution should be clear without any ambiguities and should be short without losing clarity or specifics.
---
* **Title** - The title or tag should identify one or more categories that will help readers decide if the entry is something they need to study. Can be combined with the `Problem` element
* **Problem** - Describe the problem and how users might see the problem in a paragraph.
You might also consider the following as you describe the problem:
* Under what specific conditions does this issue arise?
* Under what specific conditions are we sure this issue will not arise?
* For a performance issue, instead of saying something is a performance issue, describe what the performance impact of issue is?
* **Solution** - Describe the solution in another paragraph.
You might also consider the following as you describe the solution:
* What was done to resolve the issue?
* What is the functional impact?
* Is there a workaround – a way for users design their software so as not to encounter the issue? If so, what is the workaround?
* For a performance fix, how has the performance improved? Links to published documentation would be good.
## Building for Development
<h2 id="checklist">Checklist</h2>
### Basic CMake Build
Please make sure that you check the items applicable to your pull request:
CMake is the required build system for all platforms:
* Code
* [ ] Does the pull request have a corresponding GitHub issue and clear purpose?
* [ ] Does the pull request follow HDF5 best practices (naming conventions, code portability, code structure, etc.)? <<TODO: link to the document>>
* [ ] Is the pull request applicable to any other branches? If yes, which ones? Please document it in the GitHub issue.
* [ ] Is the new code sufficiently documented for future maintenance?
* [ ] Does the new feature require a change to an existing API? See "API Compatibility Macros" document (https://support.hdfgroup.org/documentation/hdf5/latest/api-compat-macros.html)
* Documentation
* [ ] Was the change described in the release_docs/RELEASE.txt file?
* [ ] Was the new function documented in the corresponding public header file using [Doxygen](https://support.hdfgroup.org/documentation/hdf5/latest/_r_m_t.html)?
* [ ] Was new functionality documented for the HDF5 community (the level of documentation depends on the feature; ask us what would be appropriate)
* Testing
* [ ] Does the pull request have tests?
* [ ] Does the pull request affect HDF5 library performance?
1. **Create a build directory:**
```bash
mkdir build && cd build
```
We want as many contributions as we can get, and we are here to help. Feel free to reach out to us if you have any questions
2. **Configure the build:**
```bash
cmake -G "Unix Makefiles" -DHDF5_ENABLE_DEVELOPER_MODE=ON ..
```
The `HDF5_ENABLE_DEVELOPER_MODE` option enables debug symbols, warnings as errors, and other developer-friendly settings.
Thank you for your contribution!
3. **Build the library:**
```bash
make
```
### Developer Build Tips
* **Memory Checking:** Use `HDF5_ENABLE_USING_MEMCHECKER:BOOL=ON` when using tools like Valgrind. This disables
internal memory pools that can hide memory issues.
* **Developer Warnings:** Enable extra warnings with `HDF5_ENABLE_DEV_WARNINGS:BOOL=ON` (generates significant
output but can be useful).
* **Warnings as Errors:** The CI system builds with `-Werror`, so fix all compiler warnings before submitting pull requests.
---
## Source Code Overview
Here's where to find things in the source tree:
* **`src/`**: Main C library source code
* **`test/`**: C library test code
* **`testpar/`**: Parallel C library test code
* **`tools/`**: Command-line tools (h5dump, h5repack, etc.)
* **`HDF5Examples/`**: Library examples
* **`hl/`**: High-level library source, tests, and examples
* **`c++/`**: C++ language wrapper
* **`fortran/`**: Fortran language wrapper
* **`java/`**: JNI/Java language wrapper
* **`bin/`**: Build scripts and miscellaneous tools
* **`config/`**: Configuration files for CMake
* **`doxygen/`**: Doxygen build files and documentation
* **`release_docs/`**: Install instructions and release notes
* **`utils/`**: Small utility programs
---
## Development Conventions
### Code Organization: Public, Private, and Package
HDF5 code is organized into *packages* that encapsulate related functionality (e.g., `H5D` for datasets).
Functions have three visibility levels:
* **Public:** User-facing API functions
* **Format:** `H5Xfoo()` (e.g., `H5Dcreate`)
* **Headers:** `H5Xpublic.h`
* **Private:** Internal library API, usable across packages
* **Format:** `H5X_foo()` (one underscore, e.g., `H5D_create`)
* **Package:** Used only within the defining package
* **Format:** `H5X__foo()` (two underscores, e.g., `H5D__create`)
### Function Structure
HDF5 functions follow a consistent structure for entry/exit and error handling:
```c
/*
* Function description
*/
herr_t
H5X_do_stuff(/*parameters*/)
{
/* 1. Variables declared at top */
void *foo = NULL;
herr_t ret_value = SUCCEED; /* 2. Return value variable */
FUNC_ENTER_NOAPI(FAIL) /* 3. Function entry macro */
HDassert(/*parameter check*/);
/* 4. Check for errors and goto done */
if (H5X_other_call() < 0)
HGOTO_ERROR(H5E_MAJ, H5E_MIN, FAIL, "An error occurred");
done: /* 5. Target for error jumps */
if (ret_value < 0)
/* error cleanup */
/* regular cleanup */
FUNC_LEAVE_NOAPI(ret_value); /* 6. Function leave macro */
}
```
**Public** functions use `FUNC_ENTER_API`, include `H5TRACE` macros for API tracing, and perform more rigorous parameter checking.
### Error Handling
* Almost all functions return `herr_t` or `hid_t` error codes
* `FUNC_ENTER_*` macros set up error handling stack
* `HGOTO_ERROR` pushes errors onto stack and jumps to cleanup
* `FUNC_LEAVE_*` macros return the result
* Always check return values of functions that can fail
### Platform Independence
HDF5 uses a compatibility layer for platform differences:
* Standard C and POSIX calls are prefixed with `HD` (e.g., `HDmalloc`, `HDopen`)
* `H5private.h` and `H5win32defs.h` map these to platform-specific functions
* This layer is being modernized as C99 and POSIX become universal
### Memory Management
Use HDF5's internal memory management instead of direct `malloc`/`free`:
* **`H5MM`:** General-purpose memory management (recommended for most uses)
* **`H5FL`:** Memory pools for fixed-size, frequently allocated objects (use only when performance testing shows clear benefits)
---
## Contributing Changes
### Workflow
1. **Open a GitHub issue** ([HDF5 Issues](https://github.com/HDFGroup/hdf5/issues))
- **Required** unless the change is minor (e.g., typo fix).
- Describe the problem or feature request clearly.
2. **Fork the repository** and create your branch
- Target the `develop` branch for new features and bug fixes.
- Use descriptive branch names.
3. **Make your changes**
- Follow HDF5 coding conventions.
- Add tests for new functionality or bug fixes.
- Update documentation as needed.
4. **Build and test thoroughly**
- Follow build instructions in `release_docs/INSTALL*` files.
- Ensure all tests pass.
5. **Submit a pull request (PR)**
- Address any formatting or testing issues reported by CI.
- Make sure to include the issue that the PR addresses in the description.
- Work with HDF Group developers to meet acceptance criteria.
### Acceptance Criteria
For a pull request to be accepted, it must satisfy:
* **Clear purpose:** What does it address? How does it benefit the HDF5 community?
* **Proper documentation:** Code must be documented for maintainability.
* **Testing:** Must pass HDF5 regression testing and include appropriate tests.
- We do not expect you to perform comprehensive testing across multiple platforms
before we accept the pull request.
* **Compatibility:** Must not compromise HDF5's core principles:
- 100% backward compatibility (any HDF5 file must remain readable).
- If your patch's purpose is to modify the HDF5 data model or file format, **please** discuss
this with us first. File format changes and features required by those changes can be
introduced only in a new major release.
- Machine independence (data readable across all platforms).
- Binary compatibility for maintenance releases (no changes to public APIs/structures).
* **Documentation:** New features must be properly documented. This includes using Doxygen
and providing information in release documents such as `RELEASE.txt`.
### Branching Strategy
* **Small features:** Develop in forks of the main repository.
* **Large collaborative work:** Use feature branches named `feature/<feature>` in the main repository.
* Add `BRANCH.md` file explaining branch purpose and contact info for feature branches.
---
## Testing
### Test Structure
HDF5 uses custom testing macros rather than standard frameworks. There are two systems:
#### Modern Testing (`h5test.h`) - Preferred
```c
#include "h5test.h"
static int
test_feature(void)
{
TESTING("some feature");
/* test code */
if (error_condition)
TEST_ERROR;
PASSED();
return SUCCEED;
error:
return FAIL;
}
```
#### Legacy Testing (`testhdf5.h`) - Avoid for New Code
Used only by the large `testhdf5` program. Uses global variables and should be avoided.
### Adding New Tests
**All new functionality and bug fixes must include tests.**
1. Add tests to existing test files when appropriate.
2. Create new test programs using `h5test.h` macros.
3. Avoid adding to the `testhdf5` program.
4. Update `CMakeLists.txt` in the `test/` directory.
5. Ensure tests run and pass under CMake.
---
## Documentation
### Release Notes
Write release notes for changes that affect users:
#### When to Write Release Notes
- **Required:** User-visible changes in functionality or behavior.
- **Required:** Known problems and user-reported issue fixes.
- **Not required:** Internal code changes, comments, or build process changes.
#### Release Note Format
```
- Title/Problem
Problem description paragraph explaining the issue and conditions
where it occurs.
Solution paragraph describing what was done to resolve the issue
and any functional impact or workarounds.
```
#### Entry Elements
- **Title:** Categories to help readers identify relevance.
- **Problem:** Clear description of the issue and conditions.
- **Solution:** What was done, functional impact, and any workarounds.
### API Documentation
* **Public functions:** Must have Doxygen markup in `H5Xpublic.h` headers.
* **New features:** Document in user guide content in `H5Xmodule.h` files.
* **Developer docs:** By means of well documented source.
---
## Command-Line Tools
Tools in the `tools/` directory:
- Written in C using only the **public** HDF5 API.
- Organized with central tools library (`tools/lib`) and individual tool directories.
- Use simplified error-handling compared to main library.
- Examples: `h5dump`, `h5diff`, `h5repack`.
---
## Checklist for Contributors
Before submitting your pull request, verify:
### Code
- [ ] Corresponding GitHub issue exists (unless minor change).
- [ ] Follows HDF5 conventions (naming, portability, structure).
- [ ] Applicable to other branches? (document in GitHub issue).
- [ ] Sufficiently documented for maintenance.
- [ ] API changes follow compatibility guidelines.
### Documentation
- [ ] Change described in `release_docs/RELEASE.txt`.
- [ ] New functions documented with Doxygen in public headers.
- [ ] New features documented for HDF5 community.
### Testing
- [ ] Pull request includes tests.
- [ ] Consider performance impact.
---
## Getting Help
### Resources
* **HDF Forum:** Best place for questions about HDF5 usage and development (on HDF Group website).
* **GitHub Issues:** For bug reports and feature requests.
* **Documentation:** Check existing docs on the the HDF Group website.
### Community
The HDF5 community is here to help. Don't hesitate to reach out with questions or for guidance on contributions.
---
Thank you for contributing to HDF5! Your efforts help maintain and improve one of the most widely used data formats today.
README.md
+1 -1
View File
@@ -127,7 +127,7 @@ Development code is available at our Github location:
https://github.com/HDFGroup/hdf5.git
[u1]: https://github.com/HDFGroup/hdf5/blob/develop/release_docs/RELEASE.txt
[u2]: https://github.com/HDFGroup/hdf5/blob/develop/doc/img/release-schedule.png
[u2]: https://github.com/HDFGroup/hdf5/blob/develop/release_docs/img/release-schedule.png
[u3]: https://github.com/HDFGroup/hdf5/blob/develop/doxygen/img/HDF5.png
[u4]: https://github.com/HDFGroup/hdf5/blob/develop/release_docs
doc/img/release-schedule.plantuml → release_docs/img/release-schedule.plantuml
View File
doc/img/release-schedule.png → release_docs/img/release-schedule.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 22 KiB