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

[calnan]

On Tue, 9 May 2023 16:25:51 GMT, Iris Clark <iris 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 10:
> 
>> 8:   :::
>> 9: 
>> 10: [JBS](https://bugs.openjdk.org/) is a public issue tracker used by many OpenJDK projects and is open for anyone to read and search. In order to get write access you need to be registered in the [OpenJDK Census](https://openjdk.org/census) by becoming, for instance, an [Author](https://openjdk.org/bylaws#author) in an OpenJDK [Project](https://openjdk.org/bylaws#project).
> 
> Recommend dropping "In order".

fixed

> src/guide/jbs-jdk-bug-system.md line 37:
> 
>> 35: <tr>
>> 36:     <td class="dictionary">[New Feature]{.jbs-field}</td>
>> 37:     <td class="dictionary">Not recommended to use<br /></td>
> 
> "**to** use" -> "**for** use"

fixed

> src/guide/jbs-jdk-bug-system.md line 41:
> 
>> 39: <tr>
>> 40:     <td class="dictionary">[JEP]{.jbs-field}</td>
>> 41:     <td class="dictionary">For a proposal for a significant change or new feature which will take 4 weeks or more of work - see [JEP-1](https://openjdk.org/jeps/1)</td>
> 
> "For a proposal **for** a significant" -> "For a proposal **of** a significant"

fixed

> src/guide/jbs-jdk-bug-system.md line 85:
> 
>> 83: * Including the java -fullversion is encouraged for bugs in the JVM, hangs, network issues where the exact version can be critical to determine what fixes may be missing from an older version.
>> 84: * Always file separate bugs for different issues.
>> 85:     * If two crashes looks related, but not similar enough to be sure they are the same, it's easier to later close a bug as a duplicate than it is to separate out one bug into two.
> 
> "looks" -> "look"

fixed

> src/guide/jbs-jdk-bug-system.md line 227:
> 
>> 225: ## Resolving an issue
>> 226: 
>> 227: Once the work on an issue has been completed this should be indicated in JBS by moving the issue to a "closed" state.  There are two "closed" states: [Resolved]{.jbs-field} and [Closed]{.jbs-field} which can be used interchangeably except in the case of [Fixed]{.jbs-field}, or when flagged as  [Incomplete]{.jbs-field} (See Triaging).
> 
> Do you need to mention that "Resolved, fixed" is handled automatically when a PR is pushed to a repo?  The first sentence seems to imply that resolution always requires direct user interaction in JBS.  Hmm... I see that you address this later around line 233. Maybe just modify the first sentence to something slightly more generic, e.g. "Once the work on an issue has been complete the issue should be in a 'closed' state."?

updated

> src/guide/jbs-jdk-bug-system.md line 267:
> 
>> 265: <tr>
>> 266:     <td class="dictionary">[External]{.jbs-field}</td>
>> 267:     <td class="dictionary">Use where the issue is due to a problem in a Java library (not shipped with the JDK) or an IDE or other external tool</td>
> 
> Maybe also applicable for problems in the OS or other downstream users of OpenJDK source (e.g. another VM).  It would be friendly to provide advice for reporting the problem the responsible party if that information is known.

I haven't put quite that wording as in the case of an OS issue it would seem the assignee would report it to the OS vendor

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

PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1189299490
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1189299404
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1189299263
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1189299070
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1189299009
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1189300076