RFR: Section on release notes [v6]

[David Holmes]

On 19/03/2022 5:02 am, calnan wrote:
> On Thu, 17 Mar 2022 00:33:08 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)
>>
>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>>
>>    Rewritten and added more info.
> 
> Some suggested changes to tighten up the text
> 
> src/index.md line 1553:
> 
>> 1551: When writing a release note, 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 verbatim (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.
>> 1552:
>> 1553: The release note itself is written in a [JBS](#jbs---jdk-bug-system) sub-task to the issue that is used to push the change. There are a few steps to follow for the release note to find its way from JBS to the actual release note document.
> 
> Suggestion:
> 
> The release note itself is written in a [JBS](#jbs---jdk-bug-system) sub-task linked to the issue that is used to push the change. There are a few steps to follow for the release note to find its way from JBS to the actual release note document.

Nit: It is a "sub-task _of_ the issue" not "to the issue" nor "linked to 
the issue".

Cheers,
David
-----

> src/index.md line 1556:
> 
>> 1554:
>> 1555: #. Create a sub-task (More → Create Sub-Task) for the issue that requires a release note - the main issue, that is, the JBS issue that is used to push the original change, **not** for backports or the CSR (if there is one).
>> 1556: #. For the newly created sub-task do these steps:
> 
> Suggestion:
> 
> #. For the newly created sub-task follow these steps:
> 
> src/index.md line 1563:
> 
>> 1561:    * Set the [Assignee]{.jbs} to the same person who owns the main issue.
>> 1562:    * Set [Affects Version]{.jbs} to the release versions for which the release note should be published.
>> 1563:    * Set the [Fix Version]{.jbs} to the same value that the main issue has.
> 
> Suggestion:
> 
>     * Set the [Fix Version]{.jbs} to the same value that the main issue - in almost all cases this will be the version of the mainline.
> 
> src/index.md line 1564:
> 
>> 1562:    * Set [Affects Version]{.jbs} to the release versions for which the release note should be published.
>> 1563:    * Set the [Fix Version]{.jbs} to the same value that the main issue has.
>> 1564:    * Enter the text of the release note in the [Description]{.jbs} field using markdown formatting, following the [CommonMark specification](https://spec.commonmark.org/current/). Markdown won't be rendered in JBS. You can use [dingus](https://spec.commonmark.org/dingus/) to see what the release note will look like. Note that ascii table formatting is supported but will not display correctly in the dingus page. For more information see [General Conventions for Release Notes](#general-conventions-for-release-notes) below.
> 
> Slight adjustment to text and added link to ascii table format page
> Suggestion:
> 
>     * Enter the text of the release note in the [Description]{.jbs} field using markdown formatting, following the [CommonMark specification](https://spec.commonmark.org/current/). While the markdown won't be rendered in JBS, you can use [dingus](https://spec.commonmark.org/dingus/) to see what the release note will look like. Note that [Github stlye ascii table formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables) is supported but will not display correctly in the dingus page. For more information see [General Conventions for Release Notes](#general-conventions-for-release-notes) below.
> 
> src/index.md line 1566:
> 
>> 1564:    * Enter the text of the release note in the [Description]{.jbs} field using markdown formatting, following the [CommonMark specification](https://spec.commonmark.org/current/). Markdown won't be rendered in JBS. You can use [dingus](https://spec.commonmark.org/dingus/) to see what the release note will look like. Note that ascii table formatting is supported but will not display correctly in the dingus page. For more information see [General Conventions for Release Notes](#general-conventions-for-release-notes) below.
>> 1565:    * While the [Priority]{.jbs} of the sub-task is set by default to be the same as the priority of the issue itself, it can be changed to adjust in what order the release note is listed compared to other release notes in the same build or release note section.
>> 1566: #. Ask your Reviewers to have a look at the release note. Ideally you should have the release note reviewed at the same time as the code is reviewed. If it's later determined that a release note is necessary, then go back to the same engineers who reviewed the fix to review the release note.  Special care should be taken when writing a release note that will cover changes related to a vulnerability fix in order to avoid describing the vulnerability in a way that someone can better understand how to exploit it.
> 
> Slight changes to the text to make it more direct
> Suggestion:
> 
> #. Have the release note ready to be reviewed at the same time as the code is reviewed. If it's later determined that a release note is necessary, then go back to the same engineers who reviewed the fix to review the release note.  Special care should be taken when writing a release note that will cover changes related to a vulnerability fix in order to avoid describing technical details of how it could have been exploited.
> 
> src/index.md line 1604:
> 
>> 1602: ## RN-labels
>> 1603:
>> 1604: Unless tagged otherwise it will be assumed that the release note documents a change in behavior (will have likely required a CSR) or other item which should be included in the release notes. If the note covers a more specific type of change, then one of the following labels can be included (notes of a similar type will be listed together).
> 
> s/tagged/labeled/ ?
> 
> -------------
> 
> PR: https://git.openjdk.java.net/guide/pull/75