From db4e414e4d25a9b0d6960fb98756f55176c1bf37 Mon Sep 17 00:00:00 2001 From: roger_calnan Date: Fri, 22 Nov 2024 11:22:09 -0800 Subject: [PATCH 1/3] draft of an update of guide to cover the potential addition of a causes link type --- src/guide/jbs-jdk-bug-system.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/src/guide/jbs-jdk-bug-system.md b/src/guide/jbs-jdk-bug-system.md index 03490d9..6cbce34 100644 --- a/src/guide/jbs-jdk-bug-system.md +++ b/src/guide/jbs-jdk-bug-system.md @@ -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. + +There are the following link types: + +’duplicate of` - See [Closing issues as duplicates] for more information. + +‘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 + +‘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 + +‘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] + +‘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 + +‘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. + ::: {.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. ::: From 6acfc53c3c5a23f48c65f36580a0e12ca04d04ec Mon Sep 17 00:00:00 2001 From: roger_calnan Date: Tue, 3 Dec 2024 19:26:24 -0800 Subject: [PATCH 2/3] updates from feedback --- src/guide/jbs-jdk-bug-system.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/guide/jbs-jdk-bug-system.md b/src/guide/jbs-jdk-bug-system.md index 6cbce34..7e1b6fb 100644 --- a/src/guide/jbs-jdk-bug-system.md +++ b/src/guide/jbs-jdk-bug-system.md @@ -254,17 +254,17 @@ Some additional fields should be filled out or updated as you get a better under ### 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. +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 (relates to); or when a Backport or CSR request is created; or when closing as a duplicate of another issue. There are the following link types: -’duplicate of` - See [Closing issues as duplicates] for more information. +’duplicate of` - Normally set automatically - see [Closing issues as duplicates] for more information -‘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 +‘backported by’ - Normally set automatically when creating a backport with the “More -> Create Backport” option ‘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 -‘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] +‘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] ‘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 From f47c2bb428dacdefb857dc3ba2d029bc83dab283 Mon Sep 17 00:00:00 2001 From: roger_calnan Date: Tue, 14 Jan 2025 09:59:50 -0800 Subject: [PATCH 3/3] updates from feedback - restructured the section on the causes/caused by link, moving most of the text into other relevant sections of the guide --- src/guide/backporting.md | 2 ++ src/guide/jbs-jdk-bug-system.md | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/guide/backporting.md b/src/guide/backporting.md index db13df0..5d02a38 100644 --- a/src/guide/backporting.md +++ b/src/guide/backporting.md @@ -29,6 +29,8 @@ If, for instance, there are other changes between the original one and the follo 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. +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. + And finally, if backporting each commit individually, the JBS records will clearly indicate that the followup changes have been backported as well. This is important as there is tooling that verifies that everything is done in the right way. That tooling will be confused if it can't deduct from JBS what has happened. ## Working with backports in JBS diff --git a/src/guide/jbs-jdk-bug-system.md b/src/guide/jbs-jdk-bug-system.md index 7e1b6fb..086fd51 100644 --- a/src/guide/jbs-jdk-bug-system.md +++ b/src/guide/jbs-jdk-bug-system.md @@ -228,12 +228,12 @@ Now that the issue is in the right component and has the basic information, the * For Project internal changes intended to be integrated to a Project repository rather than the JDK or JDK Updates repositories, the [Fix Version/s]{.jbs-field} should be set to [internal]{.jbs-value}, or if the [Project](https://openjdk.org/bylaws#project) is large enough to have its own [repo-*]{.jbs-value} fix version, use that. * Only one [Fix Version/s]{.jbs-field} should ever be set. If the issue is to be fixed in additional releases then separate backport issues must be created (see [Working with backports in JBS]). There are exceptions to this rule for CSRs and Release Notes. 1. Make sure the bug has all the required labels – see [JBS Label Dictionary]. - * Bugs where behavior has _incorrectly_ changed from a previous build or release: [[regression]{.jbs-label}](#regression) * Changes that don't affect product code, but are only against the regression test, or problem-listing: [[noreg-self]{.jbs-label}](#noreg-self) * Changes that don't affect product code, but are only against documentation: [[noreg-doc]{.jbs-label}](#noreg-doc) * Well contained issues that seem to be easy to fix: [[starter]{.jbs-label}](#starter) * Enhancements that are pure cleanups: [[cleanup]{.jbs-label}](#cleanup) * Project specific issues usually have their own labels as well +1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A) sure that the label [[regression]{.jbs-label}](#regression) is added. Once it is known what fix caused the regression a 'caused by' link should be added to 'B' or a causes link to '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). If 'A' has been identifed as well as a caused-by link to that issue and set the [Introduced in Build]{.jbs-field} and [Introduced in Version]{.jbs-field} fields of 'B', based on which release 'A' was fixed in. At this point move the issue into the [Open]{.jbs-value} state. @@ -268,7 +268,7 @@ There are the following link types: ‘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 -‘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. +‘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’) ::: {.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.