RFR: Addition of a causes link type

[David Holmes]

On Tue, 3 Dec 2024 22:59:53 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

NIce to see such a section being added - and I've missed a "caused-by" link for many years (why did we not have it from day one?). A few suggestions however.

Thanks

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

> 255: ### Linking Issues
> 256: 
> 257: An important aspect of any issue is making clear how it is connected/related to other issues, this linking is done when closing an issue - such as marking an issue as a duplicate and [adding a duplicate link](#closing-issues-as-duplicates) or when using the ‘Create Backport’ or ‘Create CSR’ options are used which we automatically create ‘backported by’ or ‘csr for’ links (never create an issue of type Backport or CSR by hand). The other use of linking is to associate an issue with one or more other issues that share some relation with the issue and is done during the triage or resolution of the issue.

Linking can occur at any stage of an issue's lifecycle: when it is filed, when it is triaged, when it is being worked upon, or when it is being closed. Suggestion:
> An important aspect of any issue is making clear how it is connected/related to other issues. This can occur at any stage of the issue's lifecycle. For example, as information becomes available that might suggest a cause, or similar issue; or when a Backport or CSR request is created; or when closing as a duplicate of another issue.

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

> 259: There are the following link types:
> 260: 
> 261: ’duplicate of` - See [Closing issues as duplicates] for more information.

Suggestion:

’duplicate of` - Normally set automatically - see [Closing issues as duplicates] for more information.

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

> 261: ’duplicate of` - See [Closing issues as duplicates] for more information.
> 262: 
> 263: ‘backported by’ - When creating a backport with the “More -> Create Backport” option a link is automatically created between the main issue and the new Backport

Suggestion:

‘backported by’ - Normally set automatically when creating a backport with the “More -> Create Backport” option

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

> 263: ‘backported by’ - When creating a backport with the “More -> Create Backport” option a link is automatically created between the main issue and the new Backport
> 264: 
> 265: ‘CSR for’ - 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’ - Normally created automatically when creating a CSR with the “More -> Create CSR” option a link

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

> 265: ‘CSR for’ - When creating a CSR with the “More -> Create CSR” option a link is automatically created between the main issue and the new CSR
> 266: 
> 267: ‘blocks’ - when a fix is broken down into a number of parts the ‘blocks’ link should be used to ensure they are all fixed before the main issue is considered resolved - see [implementing large changes](#implementing-large-changes]

Suggestion:

‘blocks’ - 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’ link should be used to ensure they are all fixed before the main issue is considered resolved - see [implementing large changes](#implementing-large-changes]

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

> 267: ‘blocks’ - when a fix is broken down into a number of parts the ‘blocks’ 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’ - there are no rules as to when or why to create a relates link apart from not duplicating an existing “duplicated by”, ‘backported by’, ‘csr for’ or ‘blocked by’ links. In general, you should link any other issue that has a bearing on the situation where you feel the related issue should be reviewed in order to have a better understanding of what is going on

I'd also caution against excessive linking with "relates to" - for example, if a test fails you should not link every other issue with which this test has been previously been associated just because the same test was involved. The "relates to" issue should have some significance in relation to the cause and/or fix, for the current issue.

Note that it is often the case that a "relates to" situation is later determined to be a "duplicates" situation, in which case you have to manually delete the "relates to link" after Closing. (I wonder if JBS could automate that?)

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

> 269: ‘relates to’ - there are no rules as to when or why to create a relates link apart from not duplicating an existing “duplicated by”, ‘backported by’, ‘csr for’ or ‘blocked by’ links. In general, you should link any other issue that has a bearing on the situation where you feel the related issue should be reviewed in order to have a better understanding of what is going on
> 270: 
> 271: ‘causes’/‘caused by’ - the causes link implies a stronger relationship than relates. If an issue B is filed which can be traced back to the fix for issue A then ‘A causes B’ (or ‘B was caused by A’).  A ‘causes’ link would be added to A if after the integration or release of A it is found that additional work needs to be done. This might be that extra work in another area forgotten and needs to be completed or the more common case would be that a fix ‘causes’ a change of behavior (intentional or otherwise).  For a regression, if you identify the fix that caused it, add a caused-by link to that issue and set the Introduced in Build or Introduced in Version field.  Whenever looking to backport a fix the developer should look for both ‘blocked by’ and ‘causes’ links in order to understand the set of fixes that should be backported. Likewise, if A has already been backported the new causes linked issues will need to be assessed to see if it is impor
 tant enough to be backported as well. On B make sure to set the [Introduced in Build]{.jbs-field} or [Introduced in Version]{.jbs-field} field.

It seems somewhat disproportionate to explain `caused by` in so much depth compared to the others. The backporting notes really belong elsewhere, not in this definition list. I would suggest a simpler and more succinct definition:
> 'causes'/'caused-by' - For when the current issue can be directly attributed to a code change that was integrated under another issue. When such a cause is known you can also set the 'Introduced in Version' and 'Introduced in Build' fields.

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

PR Review: https://git.openjdk.org/guide/pull/139#pullrequestreview-2477157262
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868628419
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868628759
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868629214
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868629653
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868631087
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868632292
PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868635914