RFR: Section on release notes

[Lance Andersen]

On Fri, 18 Feb 2022 01:54:43 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> The meat of the procedure here was inspired by Daniel Fuchs' comment in JDK-8273727.
> [[JDK-8273727] (prop) Canonical property storage - Java Bug System](https://bugs.openjdk.java.net/browse/JDK-8273727?focusedCommentId=14448738&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14448738)

Thank you for adding this section Jesper.

A few wordsmithing suggestions below

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

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"

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?

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?

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?

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

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

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