RFR: Section on release notes [v6]

[calnan]

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.

src/index.md line 1543:

> 1541: :::
> 1542: 
> 1543: Release notes for a product (e.g. the JDK) are part of the release deliverables. They provide a way to highlight information about a fix, such as when it may have changed behavior, or when it's decided not to fix something. While what should go into a release note isn't something that can be precisely defined, it should describe changes that are important for a user of the product to know about. These are usually things that may affect the user's decision to upgrade to the specific version. In general, the release notes should not duplicate information in other documents but can serve to highlight that a change has been made.

Suggestion:

Release notes for a product such as the JDK are part of the release deliverables providing a way to highlight information about a fix, such as when it may have changed behavior, or when it's decided not to fix something. While what should go into a release note isn't something that can be precisely defined, it should describe changes that are important for a user to take into account when they are upgrading to the specific version. While release notes should not duplicate information in other documents, they can serve to highlight that a change has been made.

src/index.md line 1545:

> 1543: Release notes for a product (e.g. the JDK) are part of the release deliverables. They provide a way to highlight information about a fix, such as when it may have changed behavior, or when it's decided not to fix something. While what should go into a release note isn't something that can be precisely defined, it should describe changes that are important for a user of the product to know about. These are usually things that may affect the user's decision to upgrade to the specific version. In general, the release notes should not duplicate information in other documents but can serve to highlight that a change has been made.
> 1544: 
> 1545: Release notes are associated with a JBS issue that has been fixed (or in some cases not been fixed) in a release. In the past these notes have been added as comments to the issue and collected at the end of a release into the official release notes. In order to allow the release notes to be generated during the course of the release (for each build) the model is now that the content of a release note is provided in a sub-task linked with the appropriate JBS issue. In OpenJDK, release notes are currently being generated for the JDK and JDK Updates projects.

Maybe remove the references to the history as we have now been using subtask for many years
Suggestion:

Release notes are associated with a JBS issue that has been fixed (or in some cases not been fixed) in a release and are generated with each build of a release. Any note should be considered as an integral part of the fix process, rather than waiting until the end of the release to determine what to write. In OpenJDK, release notes are currently being generated for the JDK and JDK Updates projects.

src/index.md line 1549:

> 1547: ## Writing a release note
> 1548: 
> 1549: Writing the release note is the responsibility of the engineer who owns the issue. The note should be generated before the fix is reviewed, or when it's determined that a fix won't be addressed in the release it was found - in the case of known issues.

Suggestion:

Writing the release note is the responsibility of the engineer who owns the issue. The note should be generated before the fix is reviewed, or in the case of known issues, when it's determined that a fix won't be possible in the release the issue was found in.

src/index.md line 1551:

> 1549: Writing the release note is the responsibility of the engineer who owns the issue. The note should be generated before the fix is reviewed, or when it's determined that a fix won't be addressed in the release it was found - in the case of known issues.
> 1550: 
> 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.

Suggestion:

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 follows a similar style.

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

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