Merge branch 'develop' into feature/coding_standardsfeature/coding_standards

6 files changed, 284 insertions, 0 deletions

diff --git a/doc/branches-explained.md b/doc/branches-explained.md
new file mode 100644
index 0000000..22b9c8f
--- /dev/null
+++ b/doc/branches-explained.md
@@ -0,0 +1,41 @@
+# HDF5 Git Branching Model Explained
+
+This document describes current HDF5 branches. 
+
+Branches are tested nightly and testing results are available at https://cdash-internal.hdfgroup.org/ and https://cdash.hdfgroup.org/. 
+Commits that break daily testing should be fixed by 3:00 pm Central time or reverted.  
+We encourage code contributors to check the status of their commits. If you have any questions, please contact help@hdfgroup.org.
+ 
+## `develop`
+Develop is the main branch whose source code always reflects a state with the latest delivered development changes for the next major release of HDF5. 
+This is also considered the integration branch, as **all** new features are integrated into this branch from respective feature branches. 
+
+## `Maintenance branches`
+
+Each currently supported release-line of HDF5 (e.g. 1.8.x, 1.10.x, 1.12.x) has a support branch with the name 1_8, 1_10, 1_12. 
+Maintenance branches are similar to the develop branch, except the source code in a maintenance branch always reflects a state 
+with the latest delivered development changes for the next **maintenance** release of that particular supported release-line of HDF5. 
+**Some** new features will be integrated into a release maintenance branch, depending on whether or not those features can be 
+introduced in minor releases.  Maintenance branches are removed when a release-line is retired from support.
+
+## `feature/*`
+Feature branches are temporary branches used to develop new features in HDF5.
+Feature branches branch off of develop and exist as long as the feature is under development. 
+When the feature is complete, the branch is merged back into develop, as well as into any support branches in which the change will be included, and then the feature branch is removed.
+
+## `release/*`
+Release branches are used to prepare a new production release. They are primarily used to allow for last minute dotting of i's and crossing of t's 
+(things like setting the release version, finalizing release notes, et cetera) and do not include new development. 
+They are created from the maintenance branch at the time of the maintenance release and have 
+names 1_8_N, 1_10_N, 1_12_N, where N is the minor release number. Once the release is  done it is tagged. 
+Patches can be applied to the release branch for patch releases that are treated as "scaled down" maintenance releases as defined by Release coordinator.
+
+## `1.X/master/*` where X is 8, 10 or 12
+These branches are used to tag 1.X.* maintenance releases.
+
+## `inactive/<name>/*`
+These branches are for experimental features that were developed in the past  and have not been merged to develop, and are not under active development. The features 
+can be out of sync with the develop branch.
+
+This document was last updated on March 16, 2021
+
diff --git a/doc/code-conventions.md b/doc/code-conventions.md
new file mode 100644
index 0000000..ff3b4cf
--- /dev/null
+++ b/doc/code-conventions.md
@@ -0,0 +1,57 @@
+# HDF5 Library Code Conventions
+
+This document describes some practices that are new, or newly
+documented, starting in 2020.
+
+## Function / Variable Attributes
+
+In H5private.h, the library provides platform-independent macros
+for qualifying function and variable definitions.
+
+### Functions that accept `printf(3)` and `scanf(3)` format strings
+
+Label functions that accept a `printf(3)`-compliant format string with
+`H5_ATTR_FORMAT(printf,format_argno,variadic_argno)`, where
+the format string is the `format_argno`th argument (counting from 1)
+and the variadic arguments start with the `variadic_argno`th.
+
+Functions that accept a `scanf(3)`-compliant format string should
+be labeled `H5_ATTR_FORMAT(scanf,format_argno,variadic_argno)`.
+
+### Functions that do never return
+
+The definition of a function that always causes the program to abort and hang
+should be labeled `H5_ATTR_NORETURN` to help the compiler see which flows of
+control are infeasible.
+
+### Other attributes
+
+**TBD**
+
+### Unused variables and parameters
+
+Compilers will warn about unused parameters and variables—developers should pay
+attention to those warnings and make an effort to prevent them.
+
+Some function parameters and variables are unused in *all* configurations of
+the project.  Ordinarily, such parameters and variables should be deleted.
+However, sometimes it is possible to foresee a parameter being used, or
+removing it would change an API, or a parameter has to be defined to conform a
+function to some function pointer type.  In those cases, it's permissible to
+mark a symbol `H5_ATTR_UNUSED`.
+
+Other parameters and variables are unused in *some* configurations of the
+project, but not all.  A symbol may fall into disuse in some configuration in
+the future—then the compiler should warn, and the symbol should not be
+defined—so developers should try to label a sometimes-unused symbol with an
+attribute that's specific to the configurations where the symbol is (or is not)
+expected to be used.  The library provides the following attributes for that
+purpose:
+
+* `H5_ATTR_DEPRECATED_USED`: used only if deprecated symbols are enabled
+* `H5_ATTR_NDEBUG_UNUSED`: used only if `NDEBUG` is *not* \#defined
+* `H5_ATTR_DEBUG_API_USED`: used if the debug API is enabled
+* `H5_ATTR_PARALLEL_UNUSED`: used only if Parallel HDF5 *is not* configured
+* `H5_ATTR_PARALLEL_USED`: used only if Parallel HDF5 *is* configured
+
+Some attributes may be phased in or phased out in the future.
diff --git a/doc/contributing.md b/doc/contributing.md
new file mode 100644
index 0000000..d32ab4d
--- /dev/null
+++ b/doc/contributing.md
@@ -0,0 +1,85 @@
+# How to contribute to HDF5
+
+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.
+
+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 COPYING 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.
+
+## Table of Contents
+
+* [Workflow](#workflow)
+* [Acceptance criteria for a pull request](#criteria)
+* [Check List](#checklist)
+
+# Workflow <A NAME="workflow"></A>
+
+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.
+
+# Acceptance criteria for a pull request <A NAME="criteria"></A>
+
+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.
+
+
+# Checklist <A NAME="checklist"></A>
+
+Please make sure that you check the items applicable to your pull request:
+
+* 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>>
+  * [ ] If changes were done to Autotools build, were they added to CMake and vice versa?
+  * [ ] 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://portal.hdfgroup.org/display/HDF5/API+Compatibility+Macros)
+* Documentation
+  * [ ] Was the change described in the release_docs/RELEASE.txt file?
+  * [ ] Was MANIFEST updated if new files had been added to the source?
+  * [ ] Was the new function documented in the corresponding public header file using [Doxygen](https://docs.hdfgroup.org/hdf5/develop/_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?
+
+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
+
+Thank you for your contribution!
diff --git a/doc/img/release-schedule.plantuml b/doc/img/release-schedule.plantuml
new file mode 100644
index 0000000..f5aa62a
--- /dev/null
+++ b/doc/img/release-schedule.plantuml
@@ -0,0 +1,45 @@
+The release timeline was generated on PlantUML (https://plantuml.com)
+
+The current script:
+
+@startuml
+title HDF5 Release Schedule
+
+projectscale monthly
+Project starts 2021-01-01
+
+[1.8] starts 2021-01-01 and lasts 114 weeks
+[1.8.22] happens 2021-02-05
+[1.8.23] happens 2022-12-31
+[1.8.23] displays on same row as [1.8.22]
+[1.8] is colored in #CC6677
+
+[1.10] starts 2021-01-01 and lasts 114 weeks
+[1.10.8] happens 2021-10-22
+[1.10.9] happens 2022-05-31
+[1.10.9] displays on same row as [1.10.8]
+[1.10] is colored in #DDCC77
+
+[1.12] starts 2021-01-01 and lasts 114 weeks
+[1.12.1] happens 2021-07-01
+[1.12.2] happens 2022-04-30
+[1.12.2] displays on same row as [1.12.1]
+[1.12] is colored in #88CCEE
+
+[1.13] starts 2021-01-01 and lasts 104 weeks
+[1.13.0] happens 2021-12-01
+[1.13.1] happens 2022-03-02
+[1.13.2] happens 2022-06-31
+[1.13.3] happens 2022-08-31
+[1.13.4] happens 2022-10-31
+[1.13.1] displays on same row as [1.13.0]
+[1.13.2] displays on same row as [1.13.0]
+[1.13.3] displays on same row as [1.13.0]
+[1.13.4] displays on same row as [1.13.0]
+[1.13] is colored in #44AA99
+
+[1.14] starts at 2022-12-31 and lasts 10 weeks
+[1.14.0] happens at 2022-12-31
+[1.14] is colored in #AA4499
+@enduml
+
diff --git a/doc/img/release-schedule.png b/doc/img/release-schedule.png
new file mode 100755
index 0000000..c2ed241
--- /dev/null
+++ b/doc/img/release-schedule.png
diff --git a/doc/library-init-shutdown.md b/doc/library-init-shutdown.md
new file mode 100644
index 0000000..917d213
--- /dev/null
+++ b/doc/library-init-shutdown.md
@@ -0,0 +1,56 @@
+# HDF5 Library initialization and shutdown
+
+## Application perspective
+
+### Implicit initialization and shutdown
+
+When a developer exports a new symbol as part of the HDF5 library,
+they should make sure that an application cannot enter the library in an
+uninitialized state through a new API function, or read an uninitialized
+value from a non-function HDF5 symbol.
+
+The HDF5 library initializes itself when an application either enters
+the library through an API function call such as `H5Fopen`, or when
+an application evaluates an HDF5 symbol that represents either a
+property-list identifier such as `H5F_ACC_RDONLY` or `H5F_ACC_RDWR`,
+a property-list class identifier such as `H5P_FILE_ACCESS`, a VFD
+identifier such as `H5FD_FAMILY` or `H5FD_SEC2`, or a type identifier
+such as `H5T_NATIVE_INT64`.
+
+The library sets a flag when initialization occurs and as long as the
+flag is set, skips initialization.
+
+The library provides a couple of macros that initialize the library
+as necessary.  The library is initialized as a side-effect of the
+`FUNC_ENTER_API*` macros used at the top of most API functions.  HDF5
+library symbols other than functions are provided through `#define`s
+that use `H5OPEN` to introduce a library-initialization call (`H5open`)
+at each site where a non-function symbol is used.
+
+Ordinarily the library registers an `atexit(3)` handler to shut itself
+down when the application exits.
+
+### Explicit initialization and shutdown
+
+An application may use an API call, `H5open`, to explicitly initialize
+the library.  `H5close` explicitly shuts down the library.
+
+## Library internals perspective
+
+No matter how library initializion begins, eventually the internal
+function `H5_init_library` will be called.  `H5_init_library` is
+responsible for calling the initializers for every internal HDF5
+library module (aka "package") in the correct order so that no module is
+initialized before its prerequisite modules.  A table in `H5_init_library`
+establishes the order of initialization.  If a developer adds a
+module to the library that it is appropriate to initialize with the rest
+of the library, then they should insert its initializer into the right
+place in the table.
+
+`H5_term_library` drives library shutdown.  Library shutdown is
+table-driven, too.  If a developer adds a module that needs to release
+resources during library shutdown, then they should add a call at the
+right place to the shutdown table.  Note that some entries in the shutdown
+table are marked as "barriers," and if a new module should only be
+shutdown *strictly after* the preceding modules, then it should be marked
+as a barrier.  See the comments in `H5_term_library` for more information.