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

[Alexey Ivanov]

On Thu, 29 Feb 2024 01:41:16 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

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 don't add both [9-na]{.jbs-label} and [11-na]{.jbs-label} — [9-na]{.jbs-label} implies all following releases therefore [11-na]{.jbs-label}, [17-na]{.jbs-label} etc. is not needed.

Suggestion:

- 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} — [9-na]{.jbs-label} implies all following releases therefore [11-na]{.jbs-label}, [17-na]{.jbs-label} etc. is not needed.

The word “example” disappeared.

I'd use “11-na, 17-na etc. _are_ not needed” to emphasise the fact there are two labels which serve as the subject of the sentence.

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.

To me, the comma before “unless” is redundant, conditional clauses after a main clause don't usually have commas before the conjunction that introduces it; however, this conditional clause is very long… Still, I wouldn't put a comma there.

With the comma before “and”, I feel the second conditional needs _a subject_ “it”; and removing “you feel that” makes the sentence shorter and clearer:
Suggestion:

    * For enhancements the [Affects Version]{.jbs-field} should be empty, unless it is only relevant to a particular release family, and (unless) it should not go into a future mainline release.

To make the sentence even clearer, you may repeat the conjunction: “_unless_ it should…”, I put it in parentheses in the suggestion.

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

PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1507319232
PR Review Comment: https://git.openjdk.org/guide/pull/119#discussion_r1507339487