RFR: Section on release notes [v2]

[Jesper Wilhelmsson]

On Fri, 18 Feb 2022 11:26:24 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fixes after reviews from David and Lance
>
> src/index.md line 690:
> 
>> 688:     </td>
>> 689:     <td class="dictionary">
>> 690:       Used to indicate wether a change requires a release note or not. The labels are always placed on the main JBS issue, never on the actual release note issue. See [Release Notes](#release-notes).
> 
> typo **wether** -> whether
> 
> You probably can omit "or not"

Fixed.

> src/index.md line 1540:
> 
>> 1538: :::
>> 1539: 
>> 1540: Release notes for a product (e.g. the JDK) are published together with a release of the given product. Release notes describe changes that are important for a user of the product to know about. This is usually things that may affect the user's choice to upgrade to the specific version.
> 
> Some suggestions:
> 
> "Release notes for a product are published together..." ->. "Release notes for a product are part of the  release deliverables "
> 
> 
>  "user's choice" -> "user's decision"

Sounds a lot better :-) Fixed.

> src/index.md line 1542:
> 
>> 1540: Release notes for a product (e.g. the JDK) are published together with a release of the given product. Release notes describe changes that are important for a user of the product to know about. This is usually things that may affect the user's choice to upgrade to the specific version.
>> 1541: 
>> 1542: When you write a release note for your feature, be prepared for rather picky review comments about grammar, typos, and wording. This is for the sake of the Java community as a whole, as the language of the release note sets the tone for many blogs and news articles. For a widely used product like the JDK, the release notes are often copied (word by word, including typos) and published to highlight news in the release. This means that we need to take extra care to make sure the text in the release note is correct and has a professional language.
> 
> "When you write a release note" ->. "When writing a release note"
> 
> 
> For the general paragraph above,  doesn't the doc team also review the release note and do some minor cleanup?

Fixed.  About the doc team, that's probably true. I'll check with them and update with that info.

> src/index.md line 1547:
> 
>> 1545: 
>> 1546: #. Add the label `release-note=yes` on the main JBS issue you want a release note for. That is, the JBS issue that is used to push the change, **not** the CSR (if there is one).
>> 1547: #. Create a sub-task of the same JBS issue that you want a release note for (not of the CSR).
> 
> The previous sentence uses "main JBS issue" and here we state "same JBS issue". We should probably. be consistent or perhaps create a bulleted list for actions agains the main JBS issue?

Rephrased and reformated the list.

> src/index.md line 1552:
> 
>> 1550:    * Add the `release-note` label to the sub-task.
>> 1551:    * Add the proper `RN-`label (see below) to the release note sub-task.
>> 1552:    * Assign the sub-task to the person who should write the release note.
> 
> This is typically the owner of the JBS issue that is being addressed so I am not sure this is needed?

Rephrased.

> src/index.md line 1587:
> 
>> 1585: 
>> 1586: Also see [release-note](#release-note).
>> 1587: 
> 
> It might be worth pointing to an example of what is considered a good release note in JBS

I'd be happy to do that. Do you have any examples of good release notes?

-------------

PR: https://git.openjdk.java.net/guide/pull/75