RFR: Addition of a causes link type [v8]

Fri Jan 24 14:54:01 UTC 2025

On Thu, 23 Jan 2025 18:50:39 GMT, Roger Calnan <duke at openjdk.org> wrote:

>> There is a proposal for the addition of a causes/caused by link type.  Tied into that there is now a separate section which covers the main link types that we use
>
> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   resolved feedback

Changes requested by aivanov (no project role).

src/guide/backporting.md line 32:

> 30: Testing each individual change is more likely to find issues than just testing the single merged change. It's also easier and less error prone to use the `/backport` command on each commit instead of manually cherrypick and deal with the merges etc.
> 31: 
> 32: Whenever looking to backport a fix the developer should look for both [blocked by]{.jbs-value} and [causes]{.jbs-value} links in order to understand the set of fixes that should be backported. Likewise, if A has already been backported the new [causes]{.jbs-value} linked issues will need to be assessed to see if it is important enough to be backported as well.

Suggestion:

Whenever looking to backport a fix, the developer should look for both [blocked by]{.jbs-value} and [causes]{.jbs-value} links in order to understand the set of fixes that should be backported. Likewise, if A has already been backported, the new [causes]{.jbs-value} linked issues will need to be assessed to see if it is important enough to be backported as well.

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

> 234:    * Enhancements that are pure cleanups: [[cleanup]{.jbs-label}](#cleanup)
> 235:    * Project specific issues usually have their own labels as well
> 236: 1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A) ensure that the label [[regression]{.jbs-label}](#regression) is added.  Once it is known what fix caused the regression a [caused by]{.jbs-value} link should be added to 'B' or a [causes]{.jbs-value} link to 'A'. A [causes]{.jbs-value} link would also be added to A if the fix _causes_ a change of behavior (intentional or otherwise) or it is found after integration, that additional work needs to be done. If 'A' has been identified as well as a adding a [caused by]{.jbs-value} link to that issue, set the [Introduced in Build]{.jbs-field} and [Introduced in Version]{.jbs-field} fields of 'B', based on which release 'A' was fixed in.  Do not add a [caused by]{.jbs-value} link if there was no specific product fix which _caused it_, for example, the addition of a test which finds an underlying problem should not be linked.

Suggestion:

1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A), ensure that the label [[regression]{.jbs-label}](#regression) is added.  Once it is known what fix caused the regression a [caused by]{.jbs-value} link should be added to 'B' or a [causes]{.jbs-value} link to 'A'. A [causes]{.jbs-value} link would also be added to 'A' if the fix _causes_ a change of behavior (intentional or otherwise) or it is found after integration, that additional work needs to be done. If 'A' has been identified as well as a adding a [caused by]{.jbs-value} link to that issue, set the [Introduced in Build]{.jbs-field} and [Introduced in Version]{.jbs-field} fields of 'B', based on which release 'A' was fixed in.  Do not add a [caused by]{.jbs-value} link if there was no specific product fix which _caused it_, for example, the addition of a test which finds an underlying problem should not be linked.

“If 'A' has been identified as well as” — identified as what? It looks as if something's missing…  
Would it be better to say, “~~as well as~~ in addition to adding a [caused by]{.jbs-value} link to that issue, set the…?

This way is clearer, in my opinion.

I'd move the _Introduced in Version_ field before _Introduced in Build_ as the version is more important.

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

> 263: [backported by]{.jbs-value} - Normally set automatically when creating a backport with the “More -> Create Backport” option, or by the Skara tooling
> 264: 
> 265: [CSR for]{.jbs-value} - When creating a CSR with the “More -> Create CSR” option a link is automatically created between the main issue and the new CSR

Suggestion:

[CSR for]{.jbs-value} - When creating a CSR with the “More -> Create CSR” option, a link is automatically created between the main issue and the new CSR

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

> 267: [blocks]{.jbs-value} - For when other issues are dependent on the current issue being resolved/fixed before they can be. For example, when a fix is broken down into a number of parts the [blocks]{.jbs-value} link should be used to ensure they are all fixed before the main issue is considered resolved - see [implementing large changes](#implementing-large-changes]
> 268: 
> 269: [relates to]{.jbs-value} - To avoid lots of relates links, the links should have some significance in relation to the cause and/or fix, for the current issue. In addition, relates links should not duplicate an existing [duplicated by]{.jbs-value}, [backported by]{.jbs-value}, [csr for]{.jbs-value} or [blocked by]{.jbs-value} link.  In particular, it may be necessary to manually remove a [relates to]{.jbs-value} link if it is later added as a [duplicated by]{.jbs-value} or [caused by]{.jbs-value} link

Suggestion:

[relates to]{.jbs-value} - To avoid lots of relates links, the links should have some significance in relation to the cause and/or fix for the current issue. In addition, relates links should not duplicate an existing [duplicated by]{.jbs-value}, [backported by]{.jbs-value}, [csr for]{.jbs-value} or [blocked by]{.jbs-value} link.  In particular, it may be necessary to manually remove a [relates to]{.jbs-value} link if it is later added as a [duplicated by]{.jbs-value} or [caused by]{.jbs-value} link

The comma in the end of the first sentence is not need, is it?

Should “relates links” be replaced with “relates to links” in the first two sentences? An italics could be used to mark them up to make it clear that these words refer to a type of the link.

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

> 269: [relates to]{.jbs-value} - To avoid lots of relates links, the links should have some significance in relation to the cause and/or fix, for the current issue. In addition, relates links should not duplicate an existing [duplicated by]{.jbs-value}, [backported by]{.jbs-value}, [csr for]{.jbs-value} or [blocked by]{.jbs-value} link.  In particular, it may be necessary to manually remove a [relates to]{.jbs-value} link if it is later added as a [duplicated by]{.jbs-value} or [caused by]{.jbs-value} link
> 270: 
> 271: [causes]{.jbs-value}/[caused by]{.jbs-value} - the causes link implies a stronger relationship than relates. If an issue 'B' can be traced back to the fix for issue 'A' then ‘A causes B’ (or ‘B was caused by A’)

Suggestion:

[causes]{.jbs-value}/[caused by]{.jbs-value} - the _causes_ link implies a stronger relationship than _relates_. If an issue 'B' can be traced back to the fix for issue 'A' then ‘A causes B’ (or ‘B is caused by A’)

Mark up the type of the link; use the same tense for both *‘A causes B’* and *‘B is caused by A’*.

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

PR Review: https://git.openjdk.org/guide/pull/139#pullrequestreview-2572812135
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928776000
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928785924
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928792116
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928798231
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928804728