RFR: Addition of a causes link type [v2]

[Jorn Vernee]

On Wed, 4 Dec 2024 02:37:59 GMT, David Holmes <dholmes at openjdk.org> wrote:

>> 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 imp
 ortant 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.
>
> I also think it will be common for a "relates" link to turn into a "cause" link, in which case we need general instructions about removing multiple links to the same issue. Ideally JBS would let us edit a link and change its type.

In some cases a fix can reveal an existing bug, e.g. because it makes an unlikely issue more likely, or because it added more tests which then find an existing bug. From the sound of it, just because a failure started to occur after commit `xyz`, doesn't necessarily mean that that commit 'causes' the issue? Some explicit guidance on whether to apply this link type in such cases would be useful I think.

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

PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1914671136