Add text about release notes (#2246)
This commit is contained in:
Allen Byrne
GitHub
@@ -1,7 +1,8 @@
|
||||
# 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.
|
||||
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.
|
||||
@@ -9,12 +10,15 @@ contribution. If in doubt, please do not hesitate to ask us for guidance.
|
||||
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.
|
||||
> 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)
|
||||
* [Release Note](#releasenote)
|
||||
* [Check List](#checklist)
|
||||
|
||||
# Workflow <A NAME="workflow"></A>
|
||||
@@ -33,8 +37,9 @@ The process for contributing code to HDF5 is as follows:
|
||||
* 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.
|
||||
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>
|
||||
|
||||
@@ -48,7 +53,8 @@ If the pull request does not have a clear purpose and benefits, it will not be a
|
||||
|
||||
* **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.
|
||||
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.
|
||||
@@ -59,6 +65,57 @@ before we accept the pull request. If the pull request does not pass regression
|
||||
|
||||
* **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.
|
||||
|
||||
|
||||
# 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.
|
||||
|
||||
# Checklist <A NAME="checklist"></A>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user