RFR: Updates to the JBS section of the OpenJDK Dev Guide [v3]

[calnan]

On Tue, 21 Mar 2023 03:03:51 GMT, David Holmes <dholmes at openjdk.org> wrote:

>> calnan has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Updates to address current round of feedback
>
> src/guide/jbs-jdk-bug-system.md line 29:
> 
>> 27: <tr>
>> 28:     <td class="dictionary">[Bug]{.jbs-field}</td>
>> 29:     <td class="dictionary">Used when reporting a problem: crashes; hangs; failures of functionality etc.</td>
> 
> The "etc" could be a bit too open to interpretation. A "bug" should relate to functional correctness - a deviation from behaviour that can be tied back to a specification. Anything else, including performance concerns, is generally not a bug but an enhancement. Though it is not clear cut as a significant performance regression may be classified as a "bug", for example.

updated description in line with above

> src/guide/jbs-jdk-bug-system.md line 34:
> 
>> 32:     <td class="dictionary"><i>Improvement</i></td>
>> 33:     <td class="dictionary">When requesting an improvement in the JDK, the issue type used depends on the size/scope of the improvement:<br />
>> 34:     ([Enhancement]{.jbs-field}) - for a small improvement to existing functionality<br />
> 
> "Enhancement" is used for improvements small and large - basically anything that is not a "bug". Perhaps we should say "small to medium" with the understanding that "large" implies big enough to be a JEP?

added "small to medium"

> src/guide/jbs-jdk-bug-system.md line 44:
> 
>> 42: <tr>
>> 43:     <td class="dictionary">[Task]{.jbs-field}</td>
>> 44:     <td class="dictionary">Where something needs to happen other than a code change - a request for a new JBS version value for example</td>
> 
> This one is very grey. "Task" does not get used much in the hotspot area, for example. I think a task may typically be something for which no changeset for the repo would be generated; though if you interpret "Task" as anything pertaining to a change other than to code, then the use of task could increase dramatically. But in the build area changes don't relate to "code" per-se, so would they all be tasks? I think not. In conclusion it is very hard to know when "Task" is suitable for use.

added new wording on tasks with a note at the end of the table to clarify that bugs and enhancements are the types that should be used to track changes to the repos

> src/guide/jbs-jdk-bug-system.md line 47:
> 
>> 45: </tr>
>> 46: <tr>
>> 47:     <td class="dictionary"><i>Vulnerability</i></td>
> 
> "Vulnerability" is not a JBS issue type, so I don't think this belongs in this table. 
> 
> Also general users may not understand what is meant by "vulnerability" here - perhaps "security vulnerability" would be better?

Removed from table and added as a note after table

> src/guide/jbs-jdk-bug-system.md line 171:
> 
>> 169: ## Triaging an issue
>> 170: 
>> 171: First give the issue a general [Review]{.jbs-field}
> 
> What does the formatting `[Review]{.jbs-field}` mean here? It is very hard to understand how this document is structured when it isn't actually using markdown as expected.

replaced with markdown formatting

> src/guide/jbs-jdk-bug-system.md line 189:
> 
>> 187:     1. if the bug also exists in older versions it may require backporting
>> 188:         * the decision to backport should be made inline with the guidelines of the lead for the release
>> 189:         * There are two options for creating backport issue(s) to track the backport: one is to create it manually once it is agreed that the bug should be backported; the second, is to let the bots create the backport issue once you push the fix to the repo.
> 
> "bots" needs some context here.

added a link to the section of the doc that better explains the "bots", will propose a follow-on update to link "bots" to the wiki page https://wiki.openjdk.org/display/SKARA

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

PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1187962795
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1187962613
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1187963478
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1187963075
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1187963678
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1187964248