Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Addition of a causes link type #139

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
+21 −2
Open

Addition of a causes link type #139

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
db4e414
draft of an update of guide to cover the potential addition of a caus…
calnan Nov 22, 2024
6acfc53
updates from feedback
calnan Dec 4, 2024
f47c2bb
updates from feedback - restructured the section on the causes/caused…
calnan Jan 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion src/guide/jbs-jdk-bug-system.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,10 +249,27 @@ Once you are made, or you make yourself, the assignee of an issue you take on th

Some additional fields should be filled out or updated as you get a better understanding of the issue:

* For a regression, if you identify the fix that caused it, add a relates-to link to that issue (and add a [[regression_]{.jbs-label}(ID)](#regression_id) label) and set the [Introduced in Build]{.jbs-field} or [Introduced in Version]{.jbs-field} field.
* The [Description]{.jbs-field} usually explains what went wrong and how the failure was found, then there's some investigation and eventually the root cause is found. At this point the [Summary]{.jbs-field} should be updated to correctly describe the bug. The [Description]{.jbs-field} however should remain a description of how the failure was found.
* The [Affects Version/s]{.jbs-field} should be updated if you in your investigation finds that the issue is older than what is indicated by the current [Affects Version/s]{.jbs-field}.

### Linking Issues

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.
calnan marked this conversation as resolved.
Show resolved Hide resolved

There are the following link types:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest marking up the issue type with bold ** if not with <dt> and using a descriptive sentence maybe, for example:

‘duplicate of’ is normally set automatically when another issue is closed as a ‘duplicate’, see [Closing issues as duplicates] for more information.

‘backported by’ is set automatically when a fix is pushed to an older release or when a backport is created manually using the More -> Create Backport option.

The list would be easier to read if the description of all the link types followed the same pattern.


’duplicate of` - See [Closing issues as duplicates] for more information.
calnan marked this conversation as resolved.
Show resolved Hide resolved

‘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
calnan marked this conversation as resolved.
Show resolved Hide resolved

‘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
calnan marked this conversation as resolved.
Show resolved Hide resolved

‘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]
calnan marked this conversation as resolved.
Show resolved Hide resolved

‘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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


‘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 important 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


::: {.note}
**Note:** If during your investigation of the bug you determine that the issue is in the wrong component, make sure to move it back to the [New]{.jbs-value} state before moving it to the new component, so that it will be picked up by the component's triage team. Make sure there is a comment outlining the reason for the move, as explained above.
:::
Expand Down