cover the documentation linking options in release notes #167

calnan · 2025-12-18T14:43:24Z

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

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace

Reviewers

Iris Clark (@irisclark - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/guide.git pull/167/head:pull/167
$ git checkout pull/167

Update a local copy of the PR:
$ git checkout pull/167
$ git pull https://git.openjdk.org/guide.git pull/167/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 167

View PR using the GUI difftool:
$ git pr show -t 167

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/guide/pull/167.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2025-12-18T14:45:10Z

👋 Welcome back calnan! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2025-12-18T14:45:15Z

@calnan This change now passes all automated pre-integration checks.

After integration, the commit message for the final commit will be:

cover the documentation linking options in release notes

Reviewed-by: iris

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been no new commits pushed to the master branch. If another commit should be pushed before you perform the /integrate command, your PR will be automatically rebased. If you prefer to avoid any potential automatic rebasing, please check the documentation for the /integrate command for further details.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@irisclark) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

mlbridge · 2025-12-18T14:48:35Z

Webrevs

openjdk · 2025-12-18T16:11:48Z

⚠️ @calnan the full name on your profile does not match the author name in this pull requests' HEAD commit. If this pull request gets integrated then the author name from this pull requests' HEAD commit will be used for the resulting commit. If you wish to push a new commit with a different author name, then please run the following commands in a local repository of your personal fork:

$ git checkout releasse-note-links
$ git commit --author='Preferred Full Name <you@example.com>' --allow-empty -m 'Update full name'
$ git push

src/guide/release-notes.md

JesperIRL · 2025-12-18T16:27:39Z

src/guide/release-notes.md

+**Linking to the Java documentation**
+
+  * the linking options defined in JavaDoc [MarkDown](https://openjdk.org/jeps/467#Links) are supported.
+  * 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."

irisclark · 2026-01-12T17:44:32Z

src/guide/release-notes.md

+  * 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]'
+  * 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 `[::]`.
+  * 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.
+  * 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}

aivanov-jdk · 2026-01-29T19:32:13Z

src/guide/release-notes.md

+   * 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.
   * Prefix the [Summary]{.jbs-field} with "Release Note:".
-   * 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.
+   * 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?

aivanov-jdk · 2026-01-29T19:34:57Z

src/guide/release-notes.md

+   * 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.
   * Prefix the [Summary]{.jbs-field} with "Release Note:".
-   * 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.
+   * 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…”*?

aivanov-jdk · 2026-01-29T19:40:13Z

src/guide/release-notes.md

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


Suggested change

* 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]'

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

aivanov-jdk · 2026-01-29T19:41:14Z

src/guide/release-notes.md

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


Suggested change

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

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

aivanov-jdk · 2026-01-29T19:46:16Z

src/guide/release-notes.md

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


Suggested change

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

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

cover the documentation linking options in release notes

e8f23e8

adjust case of text in section headings

8c8422d

openjdk bot added the rfr label Dec 18, 2025

irisclark approved these changes Dec 18, 2025

View reviewed changes

openjdk bot added the ready label Dec 18, 2025

JesperIRL reviewed Dec 18, 2025

View reviewed changes

calnan added 3 commits December 18, 2025 10:47

formatting changes

803195d

additional notes

c8597bd

additional notes

f2737a6

irisclark approved these changes Jan 12, 2026

View reviewed changes

aivanov-jdk suggested changes Jan 29, 2026

View reviewed changes

	* 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]'
	* 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]`.

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


		`https://docs.oracle.com/en/java/javase/26/docs/specs/jar/jar.html`

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

cover the documentation linking options in release notes #167

Are you sure you want to change the base?

cover the documentation linking options in release notes #167

Uh oh!

Conversation

calnan commented Dec 18, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Dec 18, 2025

Uh oh!

openjdk bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mlbridge bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

openjdk bot commented Dec 18, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

irisclark Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

calnan commented Dec 18, 2025 •

edited by openjdk bot

Loading

openjdk bot commented Dec 18, 2025 •

edited

Loading

mlbridge bot commented Dec 18, 2025 •

edited

Loading

irisclark Jan 12, 2026 •

edited

Loading