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

[Iris Clark]

On Mon, 8 May 2023 22:50:20 GMT, calnan <duke at openjdk.org> wrote:

>> Added overview on triaging issues, the bug states and process.
>
> calnan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Updates to address current round of feedback

Mostly typographic suggestions...

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

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"

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"

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"

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

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.

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

PR Review: https://git.openjdk.org/guide/pull/100#pullrequestreview-1419024444
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1188852500
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1188855869
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1188855344
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1188867488
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1188879445
PR Review Comment: https://git.openjdk.org/guide/pull/100#discussion_r1188890552