RFR: clarify how to set the affects versions

Thu Feb 15 11:36:05 UTC 2024

On Thu, 15 Feb 2024 00:04:17 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

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 a issue applicable to a feature release N it is assumed to be applicable to all (more recent) releases unless indicated otherwise (see (Rel)-na below).

Suggestion:

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

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

> 80: 
> 81: 1) If a issue applicable to a feature release N it is assumed to be applicable to all (more recent) releases unless indicated otherwise (see (Rel)-na below).
> 82:   - Note that if it is reported against an update release then all we can say is that it 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.

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

> 82:   - Note that if it is reported against an update release then all we can say is that it 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.
> 83: 
> 84: 1) If an issue is applicable to release N, then it can't be assumed that it is applicable to older releases less than N. It may be, but in general this is less important to know this as the majority of issues are only fixed in the latest feature release.  If the issue is a crash or important in another way, then it becomes worthwhile to take the time to determine if it is relevant to earlier LTS releases.

Suggestion:

1) If an issue is applicable to release N, then it can't be assumed that it is applicable to older releases less than N. It may be, but in general this is less important to know it as the majority of issues are only fixed in the latest feature release.  If the issue is a crash or important in another way, then it becomes worthwhile to take the time to determine if it is relevant to earlier LTS releases.

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

> 84: 1) If an issue is applicable to release N, then it can't be assumed that it is applicable to older releases less than N. It may be, but in general this is less important to know this as the majority of issues are only fixed in the latest feature release.  If the issue is a crash or important in another way, then it becomes worthwhile to take the time to determine if it is relevant to earlier LTS releases.
> 85: 
> 86: Another aspect of an issue is when, the feature it is a part of, was added or removed from the JDK, which in either case limits the range of releases the issue impacts.  Knowing that a feature was removed before the oldest currently supported release means it can be resolved as will-not-fix.,

Suggestion:

Another aspect of an issue is when, the feature it is a part of, was added or removed from the JDK, which in either case limits the range of releases the issue impacts.  Knowing that a feature was removed before the oldest currently supported release means it can be resolved as will-not-fix.

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

> 89: Set the [Affects Versions]{.jbs-field} field to the lowest release value that the bug is known to be reproducible on.
> 90: 
> 91: * 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 on all releases past that point (see the [Usage of (Rel)[-na]{.jbs-label} Label](#usage-of-rel-na-label)). 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.

Suggestion:

* 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 the [Usage of (Rel)[-na]{.jbs-label} Label](#usage-of-rel-na-label)). 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.

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

> 90: 
> 91: * 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 on all releases past that point (see the [Usage of (Rel)[-na]{.jbs-label} Label](#usage-of-rel-na-label)). 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.
> 92: * Do not add additional release values to [Affects Version/s]{.jbs-field} for the same release family. E.g. 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]{.jbs-value}, is encouraged, especially if there is not currently a feature release value set, or, it has been a few releases since it was last reproduced/reviewed. E.g. [Affects Version/s]{.jbs-field} is JDK [8]{.jbs-value} but it is still relevant to the latest mainline release.

Suggestion:

* Do not add additional release values to [Affects Version/s]{.jbs-field} for the same release family. E.g. 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]{.jbs-value}, is encouraged, especially if there is not currently a feature release value set, or, it has been a few releases since it was last reproduced/reviewed. E.g. [Affects Version/s]{.jbs-field} is JDK [8]{.jbs-value} but it is still relevant to the latest mainline release.

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, 17`<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 labels: you only need one, for example `9-na, 10-na` is not need as [9-na]{.jbs-label} implies any following releases

Should there be punctuation at the end of the sentences?

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, 17`<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 labels: you only need one, for example `9-na, 10-na` is not need as [9-na]{.jbs-label} implies any following releases

Suggestion:

- 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, 17`<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
- add multiple `-na` labels: you only need one, for example `9-na, 10-na` is not need 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 [7-wnf]{.jbs-label} or [9-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, both explicitly ([11-wnf]{.jbs-label} states it won't be fixed in JDK 11) or implicitly ([11-wnf]{.jbs-label} indicates it won't be fixed in JDK 8).

Suggestion:

Labels of the form [7-wnf]{.jbs-label} or [9-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, both explicitly ([11-wnf]{.jbs-label} states it won't be fixed in JDK 11) or implicitly ([11-wnf]{.jbs-label} indicates it won't be fixed in JDK 8).

The part _“…both explicitly…”_ looks confusing, or rather hard to read. Should it be _“either_ explicitly … or implicitly …”?

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

> 210:   * This may involve reproducing the bug, if doing so is fast and easy.
> 211:   * In addition to the version where the bug was found, take special care to also investigate if the bug affects mainline.
> 212:    * See [Indicating what releases an issue is applicable to](#indicating-what-releases-an-issue-is-applicable-to) for more details

This displays as just another bullet in the list, however, it clarifies the previous bullet. Should there be `<br>` instead?

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

PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490844537
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490845835
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490847399
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490848882
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490855413
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490852401
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490857229
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490871193
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490859500
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1490867797