* Build and test your changes. Detailed instructions on building and testing HDF5 can be found in the `INSTALL*` files in the `release_docs` directory.
* 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.
* **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.
# Release Note <A NAME="releasenote"></A>
* **Entry Syntax**
The release note entry syntax is shown below.
```
- Title/Problem
Problem/Solution
Signature
```
* **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.
* **Signature** - Each entry must be signed with the initials of the author, the date in YYYY/MM/DD format, and the JIRA ticket number. The
following is an example entry written by developer Xavier Zolo on April 16, 2014 about JIRA ticket HDFFV-5555: (XYZ - 2014/04/16, HDFFV-5555). The
signature is enclosed in parentheses. JIRA or Github numbers should not be used in the description of the problem or the solution. They are like
abbreviations that customers and external users will not be able to interpret.
* [ ] 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?
