RFR: Minor cleanups after the JBS re-write [v5]

[Iris Clark]

On Wed, 28 Jun 2023 14:49:41 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Using markdown tables instead of html tables.
>> Added a separate style for JBS values.
>> Minor language fixes to make it the same style as the rest of the guide.
>> Clarified some sentences.
>> Added the label jep-superseded to the dictionary.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fixed the "bad backport created" section for the new backport policy

Marked as reviewed by iris (Reviewer).

src/guide/backporting.md line 10:

> 8: :::
> 9: 
> 10: Development of the latest version of the JDK often results in bug fixes that might be interesting to include in some of the JDK update releases still being maintained. Moving a fix from a more recent release train (e.g. JDK 21) to an older release train (e.g. JDK 17) is called *backporting*.

Would it make sense to use `N` and `N-4` instead of specific releases which must be continuously maintained?

src/guide/backporting.md line 57:

> 55: ## How to fix an incorrect backport creation in JBS
> 56: 
> 57: If an issue is targeted to a release and a fix referring to that issue is pushed to a different release repository, then a backport issue is automatically created in JBS. Usually this is a "good thing", e.g., when you are backporting a fix to an earlier release, but not always... If the main issue is targeted to a later release (due to schedule planning) but someone finds the time to fix that issue in the current release, or if the main issue is targeted to a feature release in rampdown and the fix is pushed to the mainline repository, then the issue should be retargeted to the correct release before pushing the fix. However, sometimes we forget to do that.

Hmmm.  We have a "that, that" problem with this sentence and the next.  Consider removing the "to do that" at the end of this sentence.  I don't think it is necessary.  Alternatively, you could change the sentence at line 59 from "Here's how to fix that" to something like "Here's the solution".

src/guide/jbs-jdk-bug-system.md line 93:

> 91: |:-|:----------|
> 92: | [New]{.jbs-value} | Initial state after an issue is filed. Bugs in the JDK Project must be taken out of the [New]{.jbs-value} state ("Triaged" - see below) in a timely manner. In general, triaging is recommended to be done for all issue types and projects as a sign that the issue is correctly filed, and will be seen by the right developers - this is especially important towards the end of a release. |
> 93: | [Open]{.jbs-value} | Once the issue has been triaged it will be in the [Open]{.jbs-value} state and will stay here until the assignee decides to work on it, at which point it's encouraged that the "Start Work" option be selected to move it to [In Progress]{.jbs-value}. |

Recommend "an assignee".  "The assignee" implies that a bug has been assigned during triage, which is not always the case.  There are many issues in the system which don't have an assignee and that's not considered a problem.

src/guide/jbs-jdk-bug-system.md line 149:

> 147: ## Triaging an issue
> 148: 
> 149: For most JDK areas, triage is performed on a regular basis (at least weekly) by triage teams. Each triage team consists of contributors who are area experts for a specific area or feature. If you haven't been selected to be part of a triage team for a specific area *you shouldn't be triaging bugs in that area*.

I'm wondering if there should be an exception for a bug that a Committer is claiming for themselves.  Perhaps the triage teams are so large that there is no need to declare an exception?

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

PR Review: https://git.openjdk.org/guide/pull/106#pullrequestreview-1503464289
PR Review Comment: https://git.openjdk.org/guide/pull/106#discussion_r1245448946
PR Review Comment: https://git.openjdk.org/guide/pull/106#discussion_r1245442933
PR Review Comment: https://git.openjdk.org/guide/pull/106#discussion_r1245461976
PR Review Comment: https://git.openjdk.org/guide/pull/106#discussion_r1245467709