RFR: cover the documentation linking options in release notes [v4]

[Alexey Ivanov]

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