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

[calnan]

On Tue, 27 Feb 2024 13:57:40 GMT, Alexey Ivanov <aivanov at openjdk.org> wrote:

>> calnan has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   updates from feedback
>
> 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.

fixed

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

82 is meant to be a sub-bullet - it needed a couple more spaces at the start of the line

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

rewrote it a little to be clearer

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

fixed

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

fixed

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

PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1506237320
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1506233578
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1506236916
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1506234060
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1506236301