RFR: clarify how to set the affects versions [v3]

Tue Feb 27 14:24:58 UTC 2024

On Mon, 26 Feb 2024 21:04:07 GMT, calnan <duke at openjdk.org> wrote:

>> moved together information on how the set the affects version and the meaning of the (Rel)-na and (Rel)-wnf labelss
>
> calnan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   updates from feedback

Changes requested by aivanov (no project role).

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

> 79: The [Affects Version]{.jbs-field} field is used to indicate which releases an issue is applicable to, and to avoid having to set it to an exhaustive list of impacted releases the following assumptions are used to give that range:
> 80: 
> 81: 1) If an issue applicable to a feature release N it is assumed to be applicable to all (more recent) releases unless indicated otherwise (see [(Rel)-na](#usage-of-rel-na-label) below).

Suggestion:

1) If an issue is applicable to a feature release N, it is assumed to be applicable to all (more recent) releases unless indicated otherwise (see [(Rel)-na](#usage-of-rel-na-label) below).

Is _“is”_ missing? Putting a comma after the conditional clause may ease reading the sentence.

The following item has both.

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

> 80: 
> 81: 1) If an issue applicable to a feature release N it is assumed to be applicable to all (more recent) releases unless indicated otherwise (see [(Rel)-na](#usage-of-rel-na-label) below).
> 82:   - Note that if it is reported against an update release then all we can say is that it is applicable to all the following update releases, not necessarily the next feature release as it may have been introduced in an update.  Given this, it is always important to try and reproduce the issue in either the corresponding feature release or the following.

Suggestion:

      - Note that if it is reported against an update release then all we can say is that it is applicable to all the following update releases, not necessarily the next feature release as it may have been introduced in an update.  Given this, it is always important to try and reproduce the issue in either the corresponding feature release or the following.

Should this be indented to indicate it's a subitem of the first one?  
Otherwise, it renders 1. then bullet and then another 1.

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

> 104: 
> 105: - use the label to indicate that a bug is not relevant to an earlier release, for example<br>[Affects Version]{.jbs-field}: [11.0.20]{.jbs-value}, [17]{.jbs-value}<br> 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 Versions]{.jbs-field}, it is not relevant to JDK 8.
> 106: - add multiple [-na]{.jbs-label} labels: you only need one, for example [9-na]{.jbs-label}, [10-na]{.jbs-label} is not needed, as [9-na]{.jbs-label} implies any following releases.

Suggestion:

- add multiple [-na]{.jbs-label} labels: you only need one, for example if there's [9-na]{.jbs-label}, [10-na]{.jbs-label} is not needed, as [9-na]{.jbs-label} implies any following releases.

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

> 108: ##### Usage of (Rel)-wnf Label
> 109: 
> 110: labels of the form [(Rel)-wnf]{.jbs-label} (e.g. [11-wnf]{.jbs-label}) should be used to indicate that a bug is not going to be fixed in a release that it is applicable to, or any earlier releases. For example, [11-wnf]{.jbs-label} states it won't be fixed in JDK 11 and implicitly indicates it won't be fixed in JDK 8 either).

Suggestion:

Labels of the form [(Rel)-wnf]{.jbs-label} (e.g. [11-wnf]{.jbs-label}) should be used to indicate that a bug is not going to be fixed in a release that it is applicable to, or any earlier releases. For example, [11-wnf]{.jbs-label} states it won't be fixed in JDK 11 and implicitly indicates it won't be fixed in JDK 8 either).

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

> 210:   * In addition to the version where the bug was found, take special care to also investigate if the bug affects mainline.
> 211:     * See [Indicating what releases an issue is applicable to](#indicating-what-releases-an-issue-is-applicable-to) for more details.
> 212:   * For enhancements the [Affects Version]{.jbs-field} should be empty unless you feel that it is only relevant to a particular release family, and should not go into a future mainline release.

It looks these should be indented to be rendered as the subitems of “Ensure the Affects Version/s field is correct (within reason).”

It will also ensure the following item, “Set the Fix Version/s” is the 3rd item in the list rather than a first one in a new list.

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

PR Review: https://git.openjdk.org/guide/pull/119#pullrequestreview-1903582820
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1504278144
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1504303635
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1504290243
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1504291875
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1504317939