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

[Roger Calnan]

On Thu, 29 Jan 2026 19:32:13 GMT, Alexey Ivanov <aivanov 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 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?

removed ASCII as it isn't adding anything to the sentence and add a -

> 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…”*?

yes, that is reasonable

> 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.

looks like that was updated earlier, have corrected the other

> 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?

done

> 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:

fixed

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

PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2766468565
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2766469011
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2766471570
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2766474305
PR Review Comment: https://git.openjdk.org/guide/pull/167#discussion_r2766472630