From jwilhelm at openjdk.java.net Tue Feb 1 13:02:49 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Tue, 1 Feb 2022 13:02:49 GMT Subject: RFR: Backout of backport Message-ID: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> This discussion was raised in the review of #66: How should we handle the backout of a backport where the main issue is not backed out? The proposed process has been discussed in a few different forums and even though it has a few drawbacks it seems to be the solution that is most in line with our other processes and invariants. ------------- Commit messages: - Backout of backport Changes: https://git.openjdk.java.net/guide/pull/74/files Webrev: https://webrevs.openjdk.java.net/?repo=guide&pr=74&range=00 Stats: 56 lines in 1 file changed: 51 ins; 0 del; 5 mod Patch: https://git.openjdk.java.net/guide/pull/74.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/74/head:pull/74 PR: https://git.openjdk.java.net/guide/pull/74 From darcy at openjdk.java.net Tue Feb 1 18:14:26 2022 From: darcy at openjdk.java.net (Joe Darcy) Date: Tue, 1 Feb 2022 18:14:26 GMT Subject: RFR: Backout of backport In-Reply-To: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> References: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> Message-ID: On Tue, 1 Feb 2022 12:56:14 GMT, Jesper Wilhelmsson wrote: > This discussion was raised in the review of #66: How should we handle the backout of a backport where the main issue is not backed out? The proposed process has been discussed in a few different forums and even though it has a few drawbacks it seems to be the solution that is most in line with our other processes and invariants. Marked as reviewed by darcy (Committer). ------------- PR: https://git.openjdk.java.net/guide/pull/74 From jwilhelm at openjdk.java.net Fri Feb 4 14:15:33 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Fri, 4 Feb 2022 14:15:33 GMT Subject: RFR: Backout of backport In-Reply-To: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> References: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> Message-ID: On Tue, 1 Feb 2022 12:56:14 GMT, Jesper Wilhelmsson wrote: > This discussion was raised in the review of #66: How should we handle the backout of a backport where the main issue is not backed out? The proposed process has been discussed in a few different forums and even though it has a few drawbacks it seems to be the solution that is most in line with our other processes and invariants. @GoeLin Does this section cover your questions from PR #66? ------------- PR: https://git.openjdk.java.net/guide/pull/74 From iris at openjdk.java.net Fri Feb 4 18:31:23 2022 From: iris at openjdk.java.net (Iris Clark) Date: Fri, 4 Feb 2022 18:31:23 GMT Subject: RFR: Backout of backport In-Reply-To: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> References: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> Message-ID: On Tue, 1 Feb 2022 12:56:14 GMT, Jesper Wilhelmsson wrote: > This discussion was raised in the review of #66: How should we handle the backout of a backport where the main issue is not backed out? The proposed process has been discussed in a few different forums and even though it has a few drawbacks it seems to be the solution that is most in line with our other processes and invariants. Marked as reviewed by iris (Reviewer). ------------- PR: https://git.openjdk.java.net/guide/pull/74 From jwilhelm at openjdk.java.net Fri Feb 4 19:08:27 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Fri, 4 Feb 2022 19:08:27 GMT Subject: Integrated: Backout of backport In-Reply-To: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> References: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> Message-ID: On Tue, 1 Feb 2022 12:56:14 GMT, Jesper Wilhelmsson wrote: > This discussion was raised in the review of #66: How should we handle the backout of a backport where the main issue is not backed out? The proposed process has been discussed in a few different forums and even though it has a few drawbacks it seems to be the solution that is most in line with our other processes and invariants. This pull request has now been integrated. Changeset: 28b68fb7 Author: Jesper Wilhelmsson URL: https://git.openjdk.java.net/guide/commit/28b68fb76d9dfb508dfd281be57169f0088dd751 Stats: 56 lines in 1 file changed: 51 ins; 0 del; 5 mod Backout of backport Reviewed-by: darcy, iris ------------- PR: https://git.openjdk.java.net/guide/pull/74 From goetz at openjdk.java.net Mon Feb 7 08:12:20 2022 From: goetz at openjdk.java.net (Goetz Lindenmaier) Date: Mon, 7 Feb 2022 08:12:20 GMT Subject: RFR: Backout of backport In-Reply-To: References: <10G_pWqGoKrP4He2ZPTkW5WRBXY9CzgbslcJyNhgBf8=.7babb213-783c-40e3-bac2-d3facee9267f@github.com> Message-ID: On Fri, 4 Feb 2022 14:12:05 GMT, Jesper Wilhelmsson wrote: > @GoeLin Does this section cover your questions from PR #66? Sorry for missing this before. This are clear instructions how to handle this issue which is very helpful. Personally, I would have rated proper backport information in the original bug more important than not repeating bug IDs because that is what people beyond OpenJDK developers will find first. But I don't think that I could have found a majority for this. So now it's good as it is. Thanks for adding this section. ------------- PR: https://git.openjdk.java.net/guide/pull/74 From jwilhelm at openjdk.java.net Fri Feb 18 02:00:32 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Fri, 18 Feb 2022 02:00:32 GMT Subject: RFR: Section on release notes Message-ID: 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) ------------- Commit messages: - Section on release notes Changes: https://git.openjdk.java.net/guide/pull/75/files Webrev: https://webrevs.openjdk.java.net/?repo=guide&pr=75&range=00 Stats: 93 lines in 1 file changed: 64 ins; 26 del; 3 mod Patch: https://git.openjdk.java.net/guide/pull/75.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/75/head:pull/75 PR: https://git.openjdk.java.net/guide/pull/75 From dholmes at openjdk.java.net Fri Feb 18 02:52:11 2022 From: dholmes at openjdk.java.net (David Holmes) Date: Fri, 18 Feb 2022 02:52:11 GMT Subject: RFR: Section on release notes In-Reply-To: References: Message-ID: On Fri, 18 Feb 2022 01:54:43 GMT, Jesper Wilhelmsson 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) Seems quite reasonable and accurate. A couple of comments/suggestions. Thanks, David src/index.md line 1549: > 1547: #. Create a sub-task of the same JBS issue that you want a release note for (not of the CSR). > 1548: * Prefix the name of the sub-task with "Release Note:". > 1549: * The title of the release note sub-task should be a one sentence synopsis that is informative (and concise) enough to attract the attention of users, developers, and maintainers who might be impacted by the change. The title should succinctly describe what has actually changed, not be the original bug title, nor describe the problem that was being solved. It should real well as a sub-section heading in a document. src/index.md line 1554: > 1552: * Assign the sub-task to the person who should write the release note. > 1553: * Set the Fix Version of the sub-task to the same value that the main issue has. > 1554: * Enter the text of the release note in the **Description** field. Some markdown formatting is available (even though it's not rendered in JBS). Suggestion: Enter the text of the release note in the **Description** field using markdown formatting (even though it won't be rendered in JBS). ------------- Marked as reviewed by dholmes (Author). PR: https://git.openjdk.java.net/guide/pull/75 From lancea at openjdk.java.net Fri Feb 18 11:44:00 2022 From: lancea at openjdk.java.net (Lance Andersen) Date: Fri, 18 Feb 2022 11:44:00 GMT Subject: RFR: Section on release notes In-Reply-To: References: Message-ID: On Fri, 18 Feb 2022 01:54:43 GMT, Jesper Wilhelmsson 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: > 689: > 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 From jwilhelm at openjdk.java.net Fri Feb 18 22:56:42 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Fri, 18 Feb 2022 22:56:42 GMT Subject: RFR: Section on release notes In-Reply-To: References: Message-ID: On Fri, 18 Feb 2022 01:54:43 GMT, Jesper Wilhelmsson 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) David, Lance, Thank you for your review comments! I have updated the change based on all your comments. ------------- PR: https://git.openjdk.java.net/guide/pull/75 From jwilhelm at openjdk.java.net Fri Feb 18 22:56:44 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Fri, 18 Feb 2022 22:56:44 GMT Subject: RFR: Section on release notes [v2] In-Reply-To: References: Message-ID: On Fri, 18 Feb 2022 11:26:24 GMT, Lance Andersen 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: >> 689: >> 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 From jwilhelm at openjdk.java.net Fri Feb 18 22:56:42 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Fri, 18 Feb 2022 22:56:42 GMT Subject: RFR: Section on release notes [v2] In-Reply-To: References: Message-ID: > 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: Fixes after reviews from David and Lance ------------- Changes: - all: https://git.openjdk.java.net/guide/pull/75/files - new: https://git.openjdk.java.net/guide/pull/75/files/4d4c3fd8..5c03f29e Webrevs: - full: https://webrevs.openjdk.java.net/?repo=guide&pr=75&range=01 - incr: https://webrevs.openjdk.java.net/?repo=guide&pr=75&range=00-01 Stats: 14 lines in 1 file changed: 2 ins; 0 del; 12 mod Patch: https://git.openjdk.java.net/guide/pull/75.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/75/head:pull/75 PR: https://git.openjdk.java.net/guide/pull/75 From jwilhelm at openjdk.java.net Fri Feb 18 22:56:45 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Fri, 18 Feb 2022 22:56:45 GMT Subject: RFR: Section on release notes [v2] In-Reply-To: References: Message-ID: On Fri, 18 Feb 2022 02:47:39 GMT, David Holmes 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 1549: > >> 1547: #. Create a sub-task of the same JBS issue that you want a release note for (not of the CSR). >> 1548: * Prefix the name of the sub-task with "Release Note:". >> 1549: * The title of the release note sub-task should be a one sentence synopsis that is informative (and concise) enough to attract the attention of users, developers, and maintainers who might be impacted by the change. > > The title should succinctly describe what has actually changed, not be the original bug title, nor describe the problem that was being solved. It should real well as a sub-section heading in a document. Added. Did you mean "read well" or is "real well" a term that I'm not aware of in this context? > src/index.md line 1554: > >> 1552: * Assign the sub-task to the person who should write the release note. >> 1553: * Set the Fix Version of the sub-task to the same value that the main issue has. >> 1554: * Enter the text of the release note in the **Description** field. Some markdown formatting is available (even though it's not rendered in JBS). > > Suggestion: > > Enter the text of the release note in the **Description** field using markdown formatting (even though it won't be rendered in JBS). Yes, that looks better. ------------- PR: https://git.openjdk.java.net/guide/pull/75 From iris at openjdk.java.net Sat Feb 19 00:21:04 2022 From: iris at openjdk.java.net (Iris Clark) Date: Sat, 19 Feb 2022 00:21:04 GMT Subject: RFR: Section on release notes [v2] In-Reply-To: References: Message-ID: On Fri, 18 Feb 2022 22:56:42 GMT, Jesper Wilhelmsson 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: > > Fixes after reviews from David and Lance Looks good! src/index.md line 1540: > 1538: ::: > 1539: > 1540: Release notes for a product (e.g. the JDK) are part of the release deliverables. They describe changes that are important for a user of the product to know about. This is usually things that may affect the user's decision to upgrade to the specific version. "to know about. This is usually" -> "to know. These are usually" src/index.md line 1542: > 1540: Release notes for a product (e.g. the JDK) are part of the release deliverables. They describe changes that are important for a user of the product to know about. This is usually things that may affect the user's decision to upgrade to the specific version. > 1541: > 1542: When writing 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. Consider: "are often copied (word by word, including typos)" -> are often copied verbatim (including typos)" src/index.md line 1544: > 1542: When writing 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. > 1543: > 1544: The release note itself is written in a JBS sub-task to the issue that is used to push the change. There are a few steps to follow in order for the release note to find its way from JBS to the actual release note document. Consider: "to follow in order for the release note" -> "to follow for the release note" ------------- Marked as reviewed by iris (Reviewer). PR: https://git.openjdk.java.net/guide/pull/75 From iris at openjdk.java.net Sat Feb 19 00:21:05 2022 From: iris at openjdk.java.net (Iris Clark) Date: Sat, 19 Feb 2022 00:21:05 GMT Subject: RFR: Section on release notes [v2] In-Reply-To: References: Message-ID: On Fri, 18 Feb 2022 22:51:26 GMT, Jesper Wilhelmsson wrote: >> 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? Perhaps a specific issue from the 18 notes: https://jdk.java.net/18/release-notes (note that this link may be transient, but this JBS issues themselves are stable). The 17 release notes may also contain possibilities: https://www.oracle.com/java/technologies/javase/17-relnote-issues.html . ------------- PR: https://git.openjdk.java.net/guide/pull/75 From david.holmes at oracle.com Sat Feb 19 09:07:40 2022 From: david.holmes at oracle.com (David Holmes) Date: Sat, 19 Feb 2022 19:07:40 +1000 Subject: RFR: Section on release notes [v2] In-Reply-To: References: Message-ID: <96592bfb-a544-3020-ebc4-ade2e401b488@oracle.com> On 19/02/2022 8:56 am, Jesper Wilhelmsson wrote: > On Fri, 18 Feb 2022 02:47:39 GMT, David Holmes 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 1549: >> >>> 1547: #. Create a sub-task of the same JBS issue that you want a release note for (not of the CSR). >>> 1548: * Prefix the name of the sub-task with "Release Note:". >>> 1549: * The title of the release note sub-task should be a one sentence synopsis that is informative (and concise) enough to attract the attention of users, developers, and maintainers who might be impacted by the change. >> >> The title should succinctly describe what has actually changed, not be the original bug title, nor describe the problem that was being solved. It should real well as a sub-section heading in a document. > > Added. Did you mean "read well" or is "real well" a term that I'm not aware of in this context? Well that's an ironic typo. :( "read well" Thanks, David >> src/index.md line 1554: >> >>> 1552: * Assign the sub-task to the person who should write the release note. >>> 1553: * Set the Fix Version of the sub-task to the same value that the main issue has. >>> 1554: * Enter the text of the release note in the **Description** field. Some markdown formatting is available (even though it's not rendered in JBS). >> >> Suggestion: >> >> Enter the text of the release note in the **Description** field using markdown formatting (even though it won't be rendered in JBS). > > Yes, that looks better. > > ------------- > > PR: https://git.openjdk.java.net/guide/pull/75 From jwilhelm at openjdk.java.net Mon Feb 21 00:34:36 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 21 Feb 2022 00:34:36 GMT Subject: RFR: Section on release notes [v3] In-Reply-To: References: Message-ID: > 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: Fixes after Iris' review ------------- Changes: - all: https://git.openjdk.java.net/guide/pull/75/files - new: https://git.openjdk.java.net/guide/pull/75/files/5c03f29e..937f2fa8 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=guide&pr=75&range=02 - incr: https://webrevs.openjdk.java.net/?repo=guide&pr=75&range=01-02 Stats: 5 lines in 1 file changed: 1 ins; 0 del; 4 mod Patch: https://git.openjdk.java.net/guide/pull/75.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/75/head:pull/75 PR: https://git.openjdk.java.net/guide/pull/75 From jwilhelm at openjdk.java.net Mon Feb 21 00:34:37 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 21 Feb 2022 00:34:37 GMT Subject: RFR: Section on release notes [v2] In-Reply-To: References: Message-ID: <3CtkFizCJQglM6mgzkq8tCuV-TpOVW9z0n8jHfXiq3w=.1aef2d1e-efe4-4092-a693-ae79b9de218c@github.com> On Fri, 18 Feb 2022 22:56:42 GMT, Jesper Wilhelmsson 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: > > Fixes after reviews from David and Lance Than you Iris for your review! ------------- PR: https://git.openjdk.java.net/guide/pull/75 From jwilhelm at openjdk.java.net Mon Feb 21 00:34:39 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 21 Feb 2022 00:34:39 GMT Subject: RFR: Section on release notes [v2] In-Reply-To: References: Message-ID: On Sat, 19 Feb 2022 00:01:11 GMT, Iris Clark 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 1540: > >> 1538: ::: >> 1539: >> 1540: Release notes for a product (e.g. the JDK) are part of the release deliverables. They describe changes that are important for a user of the product to know about. This is usually things that may affect the user's decision to upgrade to the specific version. > > "to know about. This is usually" -> "to know. These are usually" Fixed. > src/index.md line 1542: > >> 1540: Release notes for a product (e.g. the JDK) are part of the release deliverables. They describe changes that are important for a user of the product to know about. This is usually things that may affect the user's decision to upgrade to the specific version. >> 1541: >> 1542: When writing 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. > > Consider: "are often copied (word by word, including typos)" -> are often copied verbatim (including typos)" Fixed. > src/index.md line 1544: > >> 1542: When writing 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. >> 1543: >> 1544: The release note itself is written in a JBS sub-task to the issue that is used to push the change. There are a few steps to follow in order for the release note to find its way from JBS to the actual release note document. > > Consider: "to follow in order for the release note" -> "to follow for the release note" Fixed. ------------- PR: https://git.openjdk.java.net/guide/pull/75 From jwilhelm at openjdk.java.net Mon Feb 21 00:34:40 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 21 Feb 2022 00:34:40 GMT Subject: RFR: Section on release notes [v3] In-Reply-To: References: Message-ID: On Sat, 19 Feb 2022 00:16:32 GMT, Iris Clark wrote: >> I'd be happy to do that. Do you have any examples of good release notes? > > Perhaps a specific issue from the 18 notes: https://jdk.java.net/18/release-notes (note that this link may be transient, but this JBS issues themselves are stable). The 17 release notes may also contain possibilities: https://www.oracle.com/java/technologies/javase/17-relnote-issues.html . I've added a link to the JDK Release Note index. Hopefully they are good enough to serve as examples. ------------- PR: https://git.openjdk.java.net/guide/pull/75 From jwilhelm at openjdk.java.net Mon Feb 21 00:40:39 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 21 Feb 2022 00:40:39 GMT Subject: RFR: Section on release notes [v4] In-Reply-To: References: Message-ID: > 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: Link to release note ------------- Changes: - all: https://git.openjdk.java.net/guide/pull/75/files - new: https://git.openjdk.java.net/guide/pull/75/files/937f2fa8..0d52ceb2 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=guide&pr=75&range=03 - incr: https://webrevs.openjdk.java.net/?repo=guide&pr=75&range=02-03 Stats: 4 lines in 1 file changed: 2 ins; 2 del; 0 mod Patch: https://git.openjdk.java.net/guide/pull/75.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/75/head:pull/75 PR: https://git.openjdk.java.net/guide/pull/75 From jwilhelm at openjdk.java.net Mon Feb 21 17:31:39 2022 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 21 Feb 2022 17:31:39 GMT Subject: RFR: Section on release notes [v5] In-Reply-To: References: Message-ID: <5FfTDCZtbMofekNJRgAF85rG7IhfDCmz7Cxv_mtGFUg=.05d84150-749e-4d17-8832-957de943c75e@github.com> > 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: Another release note example. ------------- Changes: - all: https://git.openjdk.java.net/guide/pull/75/files - new: https://git.openjdk.java.net/guide/pull/75/files/0d52ceb2..e4a4b604 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=guide&pr=75&range=04 - incr: https://webrevs.openjdk.java.net/?repo=guide&pr=75&range=03-04 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.java.net/guide/pull/75.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/75/head:pull/75 PR: https://git.openjdk.java.net/guide/pull/75 From iris at openjdk.java.net Mon Feb 21 19:37:11 2022 From: iris at openjdk.java.net (Iris Clark) Date: Mon, 21 Feb 2022 19:37:11 GMT Subject: RFR: Section on release notes [v5] In-Reply-To: <5FfTDCZtbMofekNJRgAF85rG7IhfDCmz7Cxv_mtGFUg=.05d84150-749e-4d17-8832-957de943c75e@github.com> References: <5FfTDCZtbMofekNJRgAF85rG7IhfDCmz7Cxv_mtGFUg=.05d84150-749e-4d17-8832-957de943c75e@github.com> Message-ID: On Mon, 21 Feb 2022 17:31:39 GMT, Jesper Wilhelmsson 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: > > Another release note example. Marked as reviewed by iris (Reviewer). src/index.md line 1561: > 1559: #. When you are done, Resolve the release note sub-task as "Delivered". > 1560: > 1561: For examples of well written release note issues in JBS, see [JDK-8276929](https://bugs.openjdk.java.net/browse/JDK-8276929) or [JDK-8278458](https://bugs.openjdk.java.net/browse/JDK-8278458). I think both of these are great in terms of the RN text. The second, 8278458 for JDK 18, uses label "RN-change" which is deprecated according to lines 1588-1589. Is this label really deprecated, or just denigrated? ------------- PR: https://git.openjdk.java.net/guide/pull/75