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

[Jesper Wilhelmsson]

On Wed, 28 Jun 2023 16:03:14 GMT, Iris Clark <iris at openjdk.org> wrote:

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

I think for the examples I'd prefer to use actual numbers. And I don't think they really needed to be updated, but I just did anyway since I was in the area.

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

Thanks. Fixed.

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

Agreed. Fixed.

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

In practice a lot of people triage their own bugs. I'm not sure if this is a good thing or not. On one hand it reduces the work for the triage team, but on the other hand we miss the verification step to make sure the bug is correctly filed. I don't think we should explicitly say that this is ok here in the guide, but each area could on an individual basis decide that experienced engineers in the team are "part of the triage team" and have the mandate to do this.

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

PR Review Comment: https://git.openjdk.org/guide/pull/106#discussion_r1245510895
PR Review Comment: https://git.openjdk.org/guide/pull/106#discussion_r1245510722
PR Review Comment: https://git.openjdk.org/guide/pull/106#discussion_r1245511114
PR Review Comment: https://git.openjdk.org/guide/pull/106#discussion_r1245511463