RFR: Updates to the JBS section of the OpenJDK Dev Guide [v3]
calnan
duke at openjdk.org
Mon May 8 22:50:25 UTC 2023
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
More information about the guide-dev
mailing list