RFR: Clarified the Affects version section

[Jesper Wilhelmsson]

On Mon, 16 Feb 2026 12:26:47 GMT, Joakim Nordström <jnordstrom at openjdk.org> wrote:

> Clarification for the [Affects version section](https://openjdk.org/guide/#usage-of-the-rel-na-label)
> 
> * Removed some newlines so things are kept in one paragraph
> * Changed some wording to make the _don'ts_ a bit clearer

Thank you for picking this up! This is an area that has been in need of improvement for some time and therefore I have a few comments that has built up over time :-)

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

> 94: Set the [Affects Version/s]{.jbs-field} field to the lowest release where the bug has been seen.
> 95: 
> 96: * The [Affects Version/s]{.jbs-field} isn't meant to be an exhaustive list of releases the issue is relevant to - it should initially be set to the release the issue was reproduced or identified on, and by implication it will be relevant to all releases past that point (see [Usage of the (Rel)[-na]{.jbs-label} Label](#usage-of-the-rel-na-label) if the issue is not applicable beyond a certain release). If it's later found to be applicable to an earlier release family then adding that earlier release is encouraged if the issue needs to be fixed in that release.

I think we can remove the entire parenthesis here. Introducing (Rel)`-na` here is confusing.

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

> 95: 
> 96: * The [Affects Version/s]{.jbs-field} isn't meant to be an exhaustive list of releases the issue is relevant to - it should initially be set to the release the issue was reproduced or identified on, and by implication it will be relevant to all releases past that point (see [Usage of the (Rel)[-na]{.jbs-label} Label](#usage-of-the-rel-na-label) if the issue is not applicable beyond a certain release). If it's later found to be applicable to an earlier release family then adding that earlier release is encouraged if the issue needs to be fixed in that release.
> 97: * Don't add additional release values to [Affects Version/s]{.jbs-field} for the same release family. For example, if there is the value [11.0.2]{.jbs-value}, don't add [11.0.5]{.jbs-value}, [11.0.7]{.jbs-value} etc. Adding an additional value for a separate release family where it's still reproducible, e.g. JDK 21, is encouraged if there isn't currently a feature release value set, or, it has been a few releases since it was last reproduced/reviewed. For example, if the [Affects Version/s]{.jbs-field} is [8]{.jbs-value}, but it is still relevant to the latest mainline release that release can be added.

Discussions in a separate thread seems to indicate that we should update this bullet to something like:
* A good rule of thumb is to include the first and the last release where the bug was seen. This does not imply that all bugs should be updated for each release just to indicate that they still exist in mainline, but if you update, make sure to remove any versions between the first and the last. Don't add additional release values to [Affects Version/s]{.jbs-field} for the same release family. For example, if there is the value [11.0.2]{.jbs-value}, don't add [11.0.5]{.jbs-value}, [11.0.7]{.jbs-value} etc.

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

> 98: * [Affects Version/s]{.jbs-field} should never use any of the "special" values available in JBS like [tbd]{.jbs-value}, [na]{.jbs-value}, [unknown]{.jbs-value}, [(Rel)-pool]{.jbs-value} or similar. Only actual JDK release numbers should be used. If you want to reflect that an issue is relevant to an older release, use a family release value or an exact release if you know where the issue was introduced: [8]{.jbs-value}, [17]{.jbs-value}, [21u4]{.jbs-value}.
> 99: 
> 100: #### Usage of the (Rel)-na Label

This could be named to be more clear, like "If an issue doesn't affect later releases, (Rel)-na"
If you change it, make sure to update links to this section.

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

> 103: 
> 104: - Don't use the label to indicate that a bug is not relevant to an earlier release. If for example [Affects Version/s]{.jbs-field} is [11.0.20]{.jbs-value}, [17]{.jbs-value} the label [8-na]{.jbs-label} would not be needed - as it doesn't have a JDK 8 release, or earlier, value in the [Affects Version/s]{.jbs-field}, it is not relevant to JDK 8. Also see [Usage of the (Rel)[-wnf]{.jbs-label} Label](#usage-of-the-rel-wnf-label)
> 105: - Never add multiple [-na]{.jbs-label} labels: you only need one. For example don't add both [9-na]{.jbs-label} and [11-na]{.jbs-label} — the [9-na]{.jbs-label} label implies all following releases therefore [11-na]{.jbs-label}, or [17-na]{.jbs-label} etc. are not needed.

I think the : can be replaced with a ,

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

> 106: - It's not recommended to specify update releases like 17u4 or 21u in the label. Labels like [17-na]{.jbs-label} and [21-na]{.jbs-label} are in general enough.
> 107: 
> 108: #### Usage of the (Rel)-wnf Label

If you change the previous header, this one should probably be updated in a similar fashion.

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

PR Review: https://git.openjdk.org/guide/pull/170#pullrequestreview-3808717954
PR Review Comment: https://git.openjdk.org/guide/pull/170#discussion_r2812517452
PR Review Comment: https://git.openjdk.org/guide/pull/170#discussion_r2812507988
PR Review Comment: https://git.openjdk.org/guide/pull/170#discussion_r2812527951
PR Review Comment: https://git.openjdk.org/guide/pull/170#discussion_r2814004693
PR Review Comment: https://git.openjdk.org/guide/pull/170#discussion_r2812531751