diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56e563d1000..b91553186fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 -* Workflow -* Acceptance criteria for a pull request -* Release Note -* Check List - -

Workflow

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

Workflow

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

Release Note

+--- -* **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 -

Checklist

+### 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.)? <> - * [ ] 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/` 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. diff --git a/README.md b/README.md index c19d1703f66..e4eb52e3420 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/doc/img/release-schedule.plantuml b/release_docs/img/release-schedule.plantuml similarity index 100% rename from doc/img/release-schedule.plantuml rename to release_docs/img/release-schedule.plantuml diff --git a/doc/img/release-schedule.png b/release_docs/img/release-schedule.png similarity index 100% rename from doc/img/release-schedule.png rename to release_docs/img/release-schedule.png