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 03490d9..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. @@ -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 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` - Normally set automatically - see [Closing issues as duplicates] for more information + +‘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’ - 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 + +‘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. :::