diff options
Diffstat (limited to 'doc/release_txt_notes.md')
-rw-r--r-- | doc/release_txt_notes.md | 107 |
1 files changed, 107 insertions, 0 deletions
diff --git a/doc/release_txt_notes.md b/doc/release_txt_notes.md new file mode 100644 index 0000000..316ba3f --- /dev/null +++ b/doc/release_txt_notes.md @@ -0,0 +1,107 @@ +# Writing Notes in a RELEASE.txt File + +## Introduction + +We have been challenged to write more helpful entries in our RELEASE.txt file +for new features, improvements, and bug fixes. To help users determine the +effects of our software changes on their applications, we have developed a +template that can be used to write release notes. The template is described on +the rest of this page. + +Some of our users face scrutiny from regulatory agencies for their use of +software they did not develop (aka SOUP). When they use our software, they have +to be aware of every change we make. For every change we make, they need to +investigate the effect the change will have on their software. If our change +affects their application, they may have to have their software retested or +re-certified. + +[SOUP](https://en.wikipedia.org/wiki/Software_of_unknown_pedigree) stands for Software Of Unknown/Uncertain Pedigree/Provenance + + +## When to write a RELEASE.txt 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. + +A release note does not need to be written for changes to the code that users +will not see. + +These things DO require a release note: + +* New features +* Changes in functionality/semantics +* Anything that changes functionality or symbols in a public header file +* Command-line tool option changes +* Adding or dropping support for compilers or operating systems +* Build system (Autotools, CMake) changes that users will encounter + +These things do NOT require a release note: + +* Internal comments +* Refactoring that does not change behavior or public headers (`H5XYpublic.h`) +* Minor build system changes (adding warning flags) + +Notes should also be added for known problems. Known problems are issues that +we know about and have not yet been able to fix. + +## RELEASE.txt entry format + +``` + - Title + + Problem + + Solution + + Signature +``` + +## RELEASE.txt entry elements + +### 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. Categories include problem +areas, tool names, and code file names. Two examples are "Memory Leak" and +"h5repack". A code file such as H5R.c or H5Z.c can be used as the title if the +problem is located in the code file. If both a title and one or more tags are +used, separate each with a period. For example, "Changed Autotools Build Behavior. Fortran." +adds the Fortran tag to the title Changed Autotools Build Behavior. Use +standard capitalization rules. + +### 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 signature is enclosed in +parentheses. + +Example: + +``` + (ABC - 2023/02/28, JIRA-12345, GitHub #1234) +``` |