From duke at openjdk.org  Fri Jan  9 13:25:47 2026
From: duke at openjdk.org (Roger Calnan)
Date: Fri, 9 Jan 2026 13:25:47 GMT
Subject: RFR: cover the documentation linking options in release notes [v4]
In-Reply-To: <_GdkmUGPtT-gHboZji92kZDpvuaQMMDu8DlExidSTaw=.ddb3682f-4f31-4b10-ab7e-520f8771c71a@github.com>
References: <_GdkmUGPtT-gHboZji92kZDpvuaQMMDu8DlExidSTaw=.ddb3682f-4f31-4b10-ab7e-520f8771c71a@github.com>
Message-ID: <5acY44Zi_HDx8D95Ng8wXurCYb26TqI4KQI9GGuvwbU=.46c7c056-62a4-4ce4-9034-7eb95264e408@github.com>

> added an explanation on the support of JavaDoc like links and the automatic linking of JBS IDs

Roger Calnan has updated the pull request incrementally with one additional commit since the last revision:

  additional notes

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

Changes:
  - all: https://git.openjdk.org/guide/pull/167/files
  - new: https://git.openjdk.org/guide/pull/167/files/c8597bd8..f2737a69

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=guide&pr=167&range=03
 - incr: https://webrevs.openjdk.org/?repo=guide&pr=167&range=02-03

  Stats: 5 lines in 1 file changed: 0 ins; 0 del; 5 mod
  Patch: https://git.openjdk.org/guide/pull/167.diff
  Fetch: git fetch https://git.openjdk.org/guide.git pull/167/head:pull/167

PR: https://git.openjdk.org/guide/pull/167

From iris at openjdk.org  Mon Jan 12 17:48:23 2026
From: iris at openjdk.org (Iris Clark)
Date: Mon, 12 Jan 2026 17:48:23 GMT
Subject: RFR: cover the documentation linking options in release notes [v4]
In-Reply-To: <5acY44Zi_HDx8D95Ng8wXurCYb26TqI4KQI9GGuvwbU=.46c7c056-62a4-4ce4-9034-7eb95264e408@github.com>
References: <_GdkmUGPtT-gHboZji92kZDpvuaQMMDu8DlExidSTaw=.ddb3682f-4f31-4b10-ab7e-520f8771c71a@github.com>
 <5acY44Zi_HDx8D95Ng8wXurCYb26TqI4KQI9GGuvwbU=.46c7c056-62a4-4ce4-9034-7eb95264e408@github.com>
Message-ID: <f-mOuKxvH30vJ5jO1je_oURkku7LCqCtZ44NRzvbJb4=.61517d6b-73a0-4ebe-bcf2-ee0ea43791d1@github.com>

On Fri, 9 Jan 2026 13:25:47 GMT, Roger Calnan <duke at openjdk.org> wrote:

>> added an explanation on the support of JavaDoc like links and the automatic linking of JBS IDs
>
> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   additional notes

Marked as reviewed by iris (Reviewer).

src/guide/release-notes.md line 86:

> 84:   * Links of the form `[NumberFormat.setStrict]`, `[NumberFormat.setStrict(boolean)]`, `[NumberFormat.setStrict(true)]`, `[ofFileChannel(FileChannel channel, long offset, long length)]` are supported with any of the separators `[.]`, `[#]` and `[::]`.
> 85:   * If a link cannot be found then the string will be rendered as if it had been enclosed in back-ticks and, in the EA release notes only, the string "(link not found)" will be added.
> 86:   * For notes of the type `rn-removed` if a link is not found then it will be looked for in the JavaDoc of the previous release family.

In the Guide's "RN Labels" section, you use "RN-Remove" as the name of the label.  Should the case match?  Also, suggest adding link to the Guides' definition of the label.

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

PR Review: https://git.openjdk.org/guide/pull/167#pullrequestreview-3651957577
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2683270765

From jwilhelm at openjdk.org  Mon Jan 12 23:30:08 2026
From: jwilhelm at openjdk.org (Jesper Wilhelmsson)
Date: Mon, 12 Jan 2026 23:30:08 GMT
Subject: RFR: cover the documentation linking options in release notes [v4]
In-Reply-To: <eu1Hr9FksQq7z74F4bw0F3RIzeLpbuTgYeMc2ahAjCo=.48fce3f9-8304-4696-a4c0-42c3c5d9a4b6@github.com>
References: <_GdkmUGPtT-gHboZji92kZDpvuaQMMDu8DlExidSTaw=.ddb3682f-4f31-4b10-ab7e-520f8771c71a@github.com>
 <CJhZUyATO9HFzrbYj98XjGvOPvkPPdKnHxAFWinUljk=.3bde420e-3051-4a93-b2b6-f7664b7dc36f@github.com>
 <eu1Hr9FksQq7z74F4bw0F3RIzeLpbuTgYeMc2ahAjCo=.48fce3f9-8304-4696-a4c0-42c3c5d9a4b6@github.com>
Message-ID: <EO5_3ZlLXbTScl84CV29STWphOT0SrZRX1bcxjekrcQ=.1b3baf7d-b8bd-40f8-9339-4555b59d78cd@github.com>

On Thu, 18 Dec 2025 18:45:51 GMT, Roger Calnan <duke at openjdk.org> wrote:

>> src/guide/release-notes.md line 81:
>> 
>>> 79: 
>>> 80:   * the linking options defined in JavaDoc [MarkDown](https://openjdk.org/jeps/467#Links) are supported.
>>> 81:   * links to the JDK tools is supported. To differentiate between `[JarSigner]` the class, and `[jarsigner]` the tool, the tool reference should be in all lowercase.
>> 
>> I think it would be nice if "JDK tools" was a link to the tools page. I know it's version specific, but the JDK 25 page should be good enough for a few years :-)
>
> you mean [JDK tools] should be a link to the tools page?

Yes, in the sentence "links to the JDK tools is supported."

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

PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2684225936

From jwilhelm at openjdk.org  Mon Jan 12 23:30:11 2026
From: jwilhelm at openjdk.org (Jesper Wilhelmsson)
Date: Mon, 12 Jan 2026 23:30:11 GMT
Subject: RFR: cover the documentation linking options in release notes [v4]
In-Reply-To: <f-mOuKxvH30vJ5jO1je_oURkku7LCqCtZ44NRzvbJb4=.61517d6b-73a0-4ebe-bcf2-ee0ea43791d1@github.com>
References: <_GdkmUGPtT-gHboZji92kZDpvuaQMMDu8DlExidSTaw=.ddb3682f-4f31-4b10-ab7e-520f8771c71a@github.com>
 <5acY44Zi_HDx8D95Ng8wXurCYb26TqI4KQI9GGuvwbU=.46c7c056-62a4-4ce4-9034-7eb95264e408@github.com>
 <f-mOuKxvH30vJ5jO1je_oURkku7LCqCtZ44NRzvbJb4=.61517d6b-73a0-4ebe-bcf2-ee0ea43791d1@github.com>
Message-ID: <H-eVJTEL_8rhH3GceYWovGZNchO6fHTLw2PlG4bnydk=.50333a79-b8f7-436f-90e1-35df5d31348c@github.com>

On Mon, 12 Jan 2026 17:44:32 GMT, Iris Clark <iris at openjdk.org> wrote:

>> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   additional notes
>
> src/guide/release-notes.md line 86:
> 
>> 84:   * Links of the form `[NumberFormat.setStrict]`, `[NumberFormat.setStrict(boolean)]`, `[NumberFormat.setStrict(true)]`, `[ofFileChannel(FileChannel channel, long offset, long length)]` are supported with any of the separators `[.]`, `[#]` and `[::]`.
>> 85:   * If a link cannot be found then the string will be rendered as if it had been enclosed in back-ticks and, in the EA release notes only, the string "(link not found)" will be added.
>> 86:   * For notes of the type `rn-removed` if a link is not found then it will be looked for in the JavaDoc of the previous release family.
> 
> In the Guide's "RN Labels" section, you use "RN-Remove" as the name of the label.  Should the case match?  Also, suggest adding link to the Guides' definition of the label.

Good catch Iris! The case should match. Also it should be [RN-Remove]{.jbs-value}

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

PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2684231827

From missa at openjdk.org  Wed Jan 21 23:15:40 2026
From: missa at openjdk.org (Mohamed Issa)
Date: Wed, 21 Jan 2026 23:15:40 GMT
Subject: RFR: Minor spelling correction in guide
Message-ID: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>

This changes fixes a typo in the **Reviewing and Sponsoring a Change** section of the guide.

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

Commit messages:
 - Correct spelling - Reviever to Reviewer

Changes: https://git.openjdk.org/guide/pull/168/files
  Webrev: https://webrevs.openjdk.org/?repo=guide&pr=168&range=00
  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/guide/pull/168.diff
  Fetch: git fetch https://git.openjdk.org/guide.git pull/168/head:pull/168

PR: https://git.openjdk.org/guide/pull/168

From jwilhelm at openjdk.org  Thu Jan 22 16:19:47 2026
From: jwilhelm at openjdk.org (Jesper Wilhelmsson)
Date: Thu, 22 Jan 2026 16:19:47 GMT
Subject: RFR: Minor spelling correction in guide
In-Reply-To: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
References: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
Message-ID: <tUIAbwv2wPae-aFAl3a9-tvJpMj8qvzpz1PHv80zU-M=.becc37d3-67ff-432b-bec0-bfd77bc01d0c@github.com>

On Wed, 21 Jan 2026 23:09:28 GMT, Mohamed Issa <missa at openjdk.org> wrote:

> This changes fixes a typo in the **Reviewing and Sponsoring a Change** section of the guide.

Marked as reviewed by jwilhelm (Lead).

Good catch!

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

PR Review: https://git.openjdk.org/guide/pull/168#pullrequestreview-3693319485
PR Comment: https://git.openjdk.org/guide/pull/168#issuecomment-3785289046

From iris at openjdk.org  Thu Jan 22 17:54:50 2026
From: iris at openjdk.org (Iris Clark)
Date: Thu, 22 Jan 2026 17:54:50 GMT
Subject: RFR: Minor spelling correction in guide
In-Reply-To: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
References: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
Message-ID: <8Ain9sD8zwl7WZvTtRHCnrDuyg4dUI-Aw5KSbr9vXSs=.800e928f-fb80-4d47-a8ee-6b2ff21c628a@github.com>

On Wed, 21 Jan 2026 23:09:28 GMT, Mohamed Issa <missa at openjdk.org> wrote:

> This changes fixes a typo in the **Reviewing and Sponsoring a Change** section of the guide.

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/guide/pull/168#pullrequestreview-3693785166

From duke at openjdk.org  Thu Jan 22 18:23:07 2026
From: duke at openjdk.org (duke)
Date: Thu, 22 Jan 2026 18:23:07 GMT
Subject: RFR: Minor spelling correction in guide
In-Reply-To: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
References: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
Message-ID: <G51tvvYqpWLfXUcA2gt6p8cTn1ww3QunPd3tqAysLmU=.3f7f9c79-96e4-4a55-a4b5-ecd30947ed26@github.com>

On Wed, 21 Jan 2026 23:09:28 GMT, Mohamed Issa <missa at openjdk.org> wrote:

> This changes fixes a typo in the **Reviewing and Sponsoring a Change** section of the guide.

@missa-prime 
Your change (at version 2b5ed9176dbe734aab8c7d51f6a1f745330e7f36) is now ready to be sponsored by a Committer.

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

PR Comment: https://git.openjdk.org/guide/pull/168#issuecomment-3785978576

From aivanov at openjdk.org  Fri Jan 23 20:58:25 2026
From: aivanov at openjdk.org (Alexey Ivanov)
Date: Fri, 23 Jan 2026 20:58:25 GMT
Subject: RFR: Minor spelling correction in guide
In-Reply-To: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
References: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
Message-ID: <vU6y6SVucx5hP9bLBfyPPWolmZDe0y0-Xpkqirc8ZtA=.2d8ad1a6-c6fd-48be-8519-b13122eb016a@github.com>

On Wed, 21 Jan 2026 23:09:28 GMT, Mohamed Issa <missa at openjdk.org> wrote:

> This changes fixes a typo in the **Reviewing and Sponsoring a Change** section of the guide.

Marked as reviewed by aivanov (no project role).

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

PR Review: https://git.openjdk.org/guide/pull/168#pullrequestreview-3699607904

From missa at openjdk.org  Fri Jan 23 22:18:44 2026
From: missa at openjdk.org (Mohamed Issa)
Date: Fri, 23 Jan 2026 22:18:44 GMT
Subject: RFR: Minor spelling correction in guide
In-Reply-To: <tUIAbwv2wPae-aFAl3a9-tvJpMj8qvzpz1PHv80zU-M=.becc37d3-67ff-432b-bec0-bfd77bc01d0c@github.com>
References: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
 <tUIAbwv2wPae-aFAl3a9-tvJpMj8qvzpz1PHv80zU-M=.becc37d3-67ff-432b-bec0-bfd77bc01d0c@github.com>
Message-ID: <HTkdXwjid6eAf2sOj0bGLkuTnuso03IH4abhU3dmwFs=.a5b1815a-ecc0-4ec5-88ea-2e7dd275d68a@github.com>

On Thu, 22 Jan 2026 16:17:07 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> This changes fixes a typo in the **Reviewing and Sponsoring a Change** section of the guide.
>
> Good catch!

@JesperIRL Could you sponsor?

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

PR Comment: https://git.openjdk.org/guide/pull/168#issuecomment-3792794169

From missa at openjdk.org  Fri Jan 23 22:31:09 2026
From: missa at openjdk.org (Mohamed Issa)
Date: Fri, 23 Jan 2026 22:31:09 GMT
Subject: Integrated: Minor spelling correction in guide
In-Reply-To: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
References: <B5rEHR_RvSRjgIzWaDrYN8_IIqqoCU4CAV1JD61DLRU=.6fa64170-24de-4533-88f7-6b9f05d72792@github.com>
Message-ID: <OEDrl1UypQgR2AaBw13TTUAlC83e-bFYWIwkKNRfBY0=.78ba950d-272a-4a93-98b3-db3a1cd9e7bd@github.com>

On Wed, 21 Jan 2026 23:09:28 GMT, Mohamed Issa <missa at openjdk.org> wrote:

> This changes fixes a typo in the **Reviewing and Sponsoring a Change** section of the guide.

This pull request has now been integrated.

Changeset: 82460a3c
Author:    Mohamed Issa <missa at openjdk.org>
Committer: Iris Clark <iris at openjdk.org>
URL:       https://git.openjdk.org/guide/commit/82460a3c3fcac194712b1c279188c52e2fdf554c
Stats:     1 line in 1 file changed: 0 ins; 0 del; 1 mod

Minor spelling correction in guide

Reviewed-by: jwilhelm, iris, aivanov

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

PR: https://git.openjdk.org/guide/pull/168

From jwilhelm at openjdk.org  Thu Jan 29 17:59:13 2026
From: jwilhelm at openjdk.org (Jesper Wilhelmsson)
Date: Thu, 29 Jan 2026 17:59:13 GMT
Subject: RFR: Select component when filing issue
Message-ID: <7ChABZcEITQsgr05FUj5TExj2-zzta9P6-cXnCkx0UA=.417f115d-004b-4397-a6ad-83a50d48dd17@github.com>

Added missing info about components when filing a JBS issue
Also clarified how to close a resolved issue through verification

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

Commit messages:
 - Select component when filing issue

Changes: https://git.openjdk.org/guide/pull/169/files
  Webrev: https://webrevs.openjdk.org/?repo=guide&pr=169&range=00
  Stats: 4 lines in 1 file changed: 3 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/guide/pull/169.diff
  Fetch: git fetch https://git.openjdk.org/guide.git pull/169/head:pull/169

PR: https://git.openjdk.org/guide/pull/169

From iris at openjdk.org  Thu Jan 29 18:34:03 2026
From: iris at openjdk.org (Iris Clark)
Date: Thu, 29 Jan 2026 18:34:03 GMT
Subject: RFR: Select component when filing issue
In-Reply-To: <7ChABZcEITQsgr05FUj5TExj2-zzta9P6-cXnCkx0UA=.417f115d-004b-4397-a6ad-83a50d48dd17@github.com>
References: <7ChABZcEITQsgr05FUj5TExj2-zzta9P6-cXnCkx0UA=.417f115d-004b-4397-a6ad-83a50d48dd17@github.com>
Message-ID: <C8JVKTZMqq454ClWL0PhBz1snT_rwPSXhUNHBt2kCVQ=.e2b9ce8b-60bc-42c1-afa0-41f7a4b640c4@github.com>

On Thu, 29 Jan 2026 17:47:28 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Added missing info about components when filing a JBS issue
> Also clarified how to close a resolved issue through verification

Marked as reviewed by iris (Reviewer).

src/guide/jbs-jdk-bug-system.md line 286:

> 284: Once the work on an issue has been completed the issue's [Status]{.jbs-field} should be in a "completed" state. There are two "completed" states: [Resolved]{.jbs-value} and [Closed]{.jbs-value}. These are accompanied by a [Resolution]{.jbs-field} and a [Fix Version/s]{.jbs-value}. Which combination of [Status]{.jbs-field}, [Resolution]{.jbs-field}, and [Fix Version/s]{.jbs-value} you should use depends on how the issue is completed.
> 285: 
> 286: Most resolutions are used to close an issue so that it ends up being [Closed]{.jbs-value} directly, but resolutions that indicates that a change has been integrated into a Project repository must go through the [Resolved]{.jbs-value} state. An issue in [Resolved]{.jbs-value} state needs to go through [verification](#verifying-an-issue) to end up as [Closed]{.jbs-value}. For the JDK Project in almost all cases the bots will transition the issue to [Resolved]{.jbs-value}/[Fixed]{.jbs-value} when the changeset is integrated to the repository. If you by accident end up in a [Resolved]{.jbs-value} state for a resolution that should only be [Closed]{.jbs-value}, use the "Verify" option in the state transition menu and select verification [None]{.jbs-value}.

Suggest "resolutions that indicate" (instead of "indicate**s**").

Also, consider changing "If you by accident" to "If you accidentally".

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

PR Review: https://git.openjdk.org/guide/pull/169#pullrequestreview-3724346069
PR Review Comment: https://git.openjdk.org/guide/pull/169#discussion_r2742957866

From aivanov at openjdk.org  Thu Jan 29 19:30:32 2026
From: aivanov at openjdk.org (Alexey Ivanov)
Date: Thu, 29 Jan 2026 19:30:32 GMT
Subject: RFR: Select component when filing issue
In-Reply-To: <7ChABZcEITQsgr05FUj5TExj2-zzta9P6-cXnCkx0UA=.417f115d-004b-4397-a6ad-83a50d48dd17@github.com>
References: <7ChABZcEITQsgr05FUj5TExj2-zzta9P6-cXnCkx0UA=.417f115d-004b-4397-a6ad-83a50d48dd17@github.com>
Message-ID: <EHKsJuwK2EY-jptl69oRkcNpLZ0QDZA9ki1AtE9Gw3w=.68e27f43-e463-47de-93a7-f945409b03b0@github.com>

On Thu, 29 Jan 2026 17:47:28 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Added missing info about components when filing a JBS issue
> Also clarified how to close a resolved issue through verification

src/guide/jbs-jdk-bug-system.md line 286:

> 284: Once the work on an issue has been completed the issue's [Status]{.jbs-field} should be in a "completed" state. There are two "completed" states: [Resolved]{.jbs-value} and [Closed]{.jbs-value}. These are accompanied by a [Resolution]{.jbs-field} and a [Fix Version/s]{.jbs-value}. Which combination of [Status]{.jbs-field}, [Resolution]{.jbs-field}, and [Fix Version/s]{.jbs-value} you should use depends on how the issue is completed.
> 285: 
> 286: Most resolutions are used to close an issue so that it ends up being [Closed]{.jbs-value} directly, but resolutions that indicates that a change has been integrated into a Project repository must go through the [Resolved]{.jbs-value} state. An issue in [Resolved]{.jbs-value} state needs to go through [verification](#verifying-an-issue) to end up as [Closed]{.jbs-value}. For the JDK Project in almost all cases the bots will transition the issue to [Resolved]{.jbs-value}/[Fixed]{.jbs-value} when the changeset is integrated to the repository. If you by accident end up in a [Resolved]{.jbs-value} state for a resolution that should only be [Closed]{.jbs-value}, use the "Verify" option in the state transition menu and select verification [None]{.jbs-value}.

Would it be clearer if the instructions suggest moving the issue to the **Closed** state? Unless resolving the issue involved integrating a changeset into a Project repository.

Perhaps, the instructions should start with the case where the issue needs to go through **Resolved**, that is when a changeset is integrated, and that happens automatically.

If one has to resolve an issue manually, it should rather go to the **Closed** state directly, which applies to any resolution other than integrating a changeset. In this case, instead of saying, *?Most resolutions are used to close??* (which I found confusing), you could state, ?All other resolutions should go directly to the **Closed** state directly.? Or something similar.

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

PR Review Comment: https://git.openjdk.org/guide/pull/169#discussion_r2743158293

From aivanov at openjdk.org  Thu Jan 29 19:49:41 2026
From: aivanov at openjdk.org (Alexey Ivanov)
Date: Thu, 29 Jan 2026 19:49:41 GMT
Subject: RFR: cover the documentation linking options in release notes [v4]
In-Reply-To: <5acY44Zi_HDx8D95Ng8wXurCYb26TqI4KQI9GGuvwbU=.46c7c056-62a4-4ce4-9034-7eb95264e408@github.com>
References: <_GdkmUGPtT-gHboZji92kZDpvuaQMMDu8DlExidSTaw=.ddb3682f-4f31-4b10-ab7e-520f8771c71a@github.com>
 <5acY44Zi_HDx8D95Ng8wXurCYb26TqI4KQI9GGuvwbU=.46c7c056-62a4-4ce4-9034-7eb95264e408@github.com>
Message-ID: <QKAx6PXAb9B_Do2KaLpz7cEGwHmce_Rv3EnO19HNkoY=.46e392f6-d29d-4cad-831e-b56cba73d965@github.com>

On Fri, 9 Jan 2026 13:25:47 GMT, Roger Calnan <duke at openjdk.org> wrote:

>> added an explanation on the support of JavaDoc like links and the automatic linking of JBS IDs
>
> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   additional notes

Changes requested by aivanov (no project role).

src/guide/release-notes.md line 31:

> 29:    * The [Summary]{.jbs-field} 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. It should succinctly describe what has actually changed, not be the original bug title, nor describe the problem that was being solved. It should read well as a subsection heading in a document.
> 30:    * Prefix the [Summary]{.jbs-field} with "Release Note:".
> 31:    * Enter the text of the release note in the [Description]{.jbs-field} 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 style 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] below.

> GitHub style ascii table formatting

Shouldn't *ASCII* be in all capital letters?

Shouldn't *GitHub-style* be hyphenated?

src/guide/release-notes.md line 31:

> 29:    * The [Summary]{.jbs-field} 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. It should succinctly describe what has actually changed, not be the original bug title, nor describe the problem that was being solved. It should read well as a subsection heading in a document.
> 30:    * Prefix the [Summary]{.jbs-field} with "Release Note:".
> 31:    * Enter the text of the release note in the [Description]{.jbs-field} 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 style 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] below.

Is *a comma* recommended in this case: (?For more information, see??*?

src/guide/release-notes.md line 82:

> 80:   * The linking options similar to those for [JavaDoc MarkDown](https://openjdk.org/jeps/467#Links) are supported.
> 81:   * Linking to the JDK tools is supported - differentiate between `[JarSigner]` the class, and `[jarsigner]` the tool, the tool reference should be in all lowercase.
> 82:   * Linking to the JDK tools command line arguments is supported for JDK 27 and above, for example `[-XX:+UseTransparentHugePages]`

Suggestion:

  * Linking to the JDK tools command line arguments is supported for JDK 27 and above, for example `[-XX:+UseTransparentHugePages]`.

Full stop in the end of the sentence?

Only two items in this list don't have full stops, which looks inconsistent.

src/guide/release-notes.md line 83:

> 81:   * Linking to the JDK tools is supported - differentiate between `[JarSigner]` the class, and `[jarsigner]` the tool, the tool reference should be in all lowercase.
> 82:   * Linking to the JDK tools command line arguments is supported for JDK 27 and above, for example `[-XX:+UseTransparentHugePages]`
> 83:   * Method names do not need to be prefixed with their class name if they are unique within the JDK, for example '[getTotalGcCpuTime()]'. Where there are multiple methods with the same name, a plain reference to the method can be achieved with '[enquoteIdentifier][Statement.enquoteIdentifier]'

Suggestion:

  * Method names do not need to be prefixed with their class name if they are unique within the JDK, for example `[getTotalGcCpuTime()]`. Where there are multiple methods with the same name, a plain reference to the method can be achieved with `[enquoteIdentifier][Statement.enquoteIdentifier]`.

Backticks to indicate a code-like syntax to use in the release note text; this would align with similar usages above and below.

Full stop in the end of the sentence?

src/guide/release-notes.md line 95:

> 93: `https://docs.oracle.com/en/java/javase/26/docs/specs/jar/jar.html`
> 94: 
> 95: and, in the EA versions of the release notes, any links which refer the to feature release under development will be translated to:

Suggestion:

and, in the EA versions of the release notes, any links which refer to the feature release under development will be translated to:

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

PR Review: https://git.openjdk.org/guide/pull/167#pullrequestreview-3724605287
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2743183004
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2743193650
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2743214755
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2743211315
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2743236487