From jvernee at openjdk.org Tue Jan 14 11:34:55 2025 From: jvernee at openjdk.org (Jorn Vernee) Date: Tue, 14 Jan 2025 11:34:55 GMT Subject: RFR: Addition of a causes link type [v2] In-Reply-To: References: Message-ID: On Wed, 4 Dec 2024 02:37:59 GMT, David Holmes 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 From duke at openjdk.org Tue Jan 14 18:03:18 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 14 Jan 2025 18:03:18 GMT Subject: RFR: Addition of a causes link type [v3] In-Reply-To: References: Message-ID: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> > 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 Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: updates from feedback - restructured the section on the causes/caused by link, moving most of the text into other relevant sections of the guide ------------- Changes: - all: https://git.openjdk.org/guide/pull/139/files - new: https://git.openjdk.org/guide/pull/139/files/6acfc53c..f47c2bb4 Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=139&range=02 - incr: https://webrevs.openjdk.org/?repo=guide&pr=139&range=01-02 Stats: 5 lines in 2 files changed: 3 ins; 1 del; 1 mod Patch: https://git.openjdk.org/guide/pull/139.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/139/head:pull/139 PR: https://git.openjdk.org/guide/pull/139 From aivanov at openjdk.org Tue Jan 14 19:45:57 2025 From: aivanov at openjdk.org (Alexey Ivanov) Date: Tue, 14 Jan 2025 19:45:57 GMT Subject: RFR: Addition of a causes link type [v3] In-Reply-To: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> References: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> Message-ID: On Tue, 14 Jan 2025 18:03:18 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > updates from feedback - restructured the section on the causes/caused by link, moving most of the text into other relevant sections of the guide Changes requested by aivanov (no project role). src/guide/backporting.md line 32: > 30: 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. > 31: > 32: 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. Suggestion: 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. Maybe even use _italics_ for the relation ship type? ??for both _?blocked by?_ and ?_causes?_ links?? and ??the new _?causes?_ linked issues?? src/guide/jbs-jdk-bug-system.md line 236: > 234: * Enhancements that are pure cleanups: [[cleanup]{.jbs-label}](#cleanup) > 235: * Project specific issues usually have their own labels as well > 236: 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. Suggestion: 1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A) ensure 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 identified 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. In ??a ?caused by? link should be added to 'B' or a ?causes? link to 'A'?, the word ?causes? needs the single-quotes to refer to the type of the link. (Also for consistency with other instances.) In ??that a fix _?causes?_ a change of behavior??, the word ?causes? should not have the quotes because the verb is used in its literal meaning rather being a type. I find it really hard to understand the last two sentences in this paragraph. ?This might be that extra work in another area was forgotten?? ? is ?was? missing here? The part after ?or?: if I understand correctly, _?the more common case?_ is a clarification, wrapping it the commas, dashes or parentheses could be easier to understand. However, it it's the most common case, should it be listed first, instead? In the last sentence, ?If 'A' has been identified as well as a caused-by link?? what does ?as well as? compare to? Is it just ?as?? And the link type should have the single quotes around it and not have the hyphen ??as a _?caused by?_ link??. Using italics for marking up the link type (in addition to the single quotes) could clarify where the text refers to a type rather than uses the verbs literally. 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 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. 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 (relates to). This should be enough as an example. The following list presents what link types are available and their meaning. src/guide/jbs-jdk-bug-system.md line 259: > 257: 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. > 258: > 259: There are the following link types: I suggest marking up the issue type with bold `**` if not with `
` 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. src/guide/jbs-jdk-bug-system.md line 261: > 259: There are the following link types: > 260: > 261: ?duplicate of` - Normally set automatically - see [Closing issues as duplicates] for more information Suggestion: ?duplicate of? - Normally set automatically - see [Closing issues as duplicates] for more information Does markdown support a definition list? Should we use HTML `
` and `
`, `
` tags to mark up the list? src/guide/jbs-jdk-bug-system.md line 263: > 261: ?duplicate of` - Normally set automatically - see [Closing issues as duplicates] for more information > 262: > 263: ?backported by? - Normally set automatically when creating a backport with the ?More -> Create Backport? option Or when the backport is integrated? 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?) Suggestion: ?causes?/?caused by? - the ?causes? link implies a stronger relationship than ?relates to?. If an issue 'B' is traced back to the fix for issue 'A' then ?A causes B? (or ?B was caused by A?) Should it be ?B _is_ caused by A?? In the above text about regressions, issue A and B have dumb single quotes around them. This should be consistent here, therefore I added them in the suggestion. ------------- PR Review: https://git.openjdk.org/guide/pull/139#pullrequestreview-2550770549 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1915446948 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1915470518 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1915475184 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1915493093 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1915480652 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1915483051 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1915504442 From ihse at openjdk.org Mon Jan 20 21:25:48 2025 From: ihse at openjdk.org (Magnus Ihse Bursie) Date: Mon, 20 Jan 2025 21:25:48 GMT Subject: RFR: Addition of a causes link type [v3] In-Reply-To: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> References: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> Message-ID: On Tue, 14 Jan 2025 18:03:18 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > updates from feedback - restructured the section on the causes/caused by link, moving most of the text into other relevant sections of the guide How should the causes/caused by link be used when a fix is backed out, and then redone? Since this is a bit of a tricky albeit somewhat common situation, maybe we should clarify it in the guide? ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2603246177 From duke at openjdk.org Tue Jan 21 18:29:28 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 18:29:28 GMT Subject: RFR: Addition of a causes link type [v4] In-Reply-To: References: Message-ID: > 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 Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: updates from feedback ------------- Changes: - all: https://git.openjdk.org/guide/pull/139/files - new: https://git.openjdk.org/guide/pull/139/files/f47c2bb4..162079eb Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=139&range=03 - incr: https://webrevs.openjdk.org/?repo=guide&pr=139&range=02-03 Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.org/guide/pull/139.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/139/head:pull/139 PR: https://git.openjdk.org/guide/pull/139 From duke at openjdk.org Tue Jan 21 18:29:30 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 18:29:30 GMT Subject: RFR: Addition of a causes link type [v4] In-Reply-To: References: Message-ID: <8ra7vnd1hPrAqEUtC3b38Zo50sBfO1viPfHHKjc9ALI=.251d8753-8c65-4656-8ad0-db881e61784b@github.com> On Wed, 4 Dec 2024 02:30:15 GMT, David Holmes wrote: >> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: >> >> updates from feedback > > 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?) reworded the section to make it clearer that relates links should have 'some significance' - agreed it would be useful if JIRA could update the relates link if it later used as a duplicate. Will see if there is a way to spot this so that they might be manually cleaned up ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1924191364 From duke at openjdk.org Tue Jan 21 18:29:31 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 18:29:31 GMT Subject: RFR: Addition of a causes link type [v4] In-Reply-To: References: Message-ID: On Tue, 14 Jan 2025 11:32:03 GMT, Jorn Vernee wrote: >> 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. refactored the text so that it now in more appropriate sections Jorn - added a sentence "Triaging an Issue" section to cover your point - please review ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1924192933 From duke at openjdk.org Tue Jan 21 19:24:05 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 19:24:05 GMT Subject: RFR: Addition of a causes link type [v5] In-Reply-To: References: Message-ID: > 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 Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: updated link name formatting ------------- Changes: - all: https://git.openjdk.org/guide/pull/139/files - new: https://git.openjdk.org/guide/pull/139/files/162079eb..e5ade95b Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=139&range=04 - incr: https://webrevs.openjdk.org/?repo=guide&pr=139&range=03-04 Stats: 8 lines in 2 files changed: 0 ins; 0 del; 8 mod Patch: https://git.openjdk.org/guide/pull/139.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/139/head:pull/139 PR: https://git.openjdk.org/guide/pull/139 From duke at openjdk.org Tue Jan 21 19:24:05 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 19:24:05 GMT Subject: RFR: Addition of a causes link type [v3] In-Reply-To: References: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> Message-ID: On Tue, 14 Jan 2025 18:54:34 GMT, Alexey Ivanov wrote: >> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: >> >> 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 line 32: > >> 30: 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. >> 31: >> 32: 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. > > Suggestion: > > 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. > > Maybe even use _italics_ for the relation ship type? ??for both _?blocked by?_ and ?_causes?_ links?? and ??the new _?causes?_ linked issues?? checked with Jesper and have changed them all to [name]{.jbs-value} ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1924254047 From duke at openjdk.org Tue Jan 21 19:41:04 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 19:41:04 GMT Subject: RFR: Addition of a causes link type [v6] In-Reply-To: References: Message-ID: > 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 Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: restructured the 'managing regressions' section ------------- Changes: - all: https://git.openjdk.org/guide/pull/139/files - new: https://git.openjdk.org/guide/pull/139/files/e5ade95b..c41a42fb Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=139&range=05 - incr: https://webrevs.openjdk.org/?repo=guide&pr=139&range=04-05 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/guide/pull/139.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/139/head:pull/139 PR: https://git.openjdk.org/guide/pull/139 From duke at openjdk.org Tue Jan 21 19:41:04 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 19:41:04 GMT Subject: RFR: Addition of a causes link type [v3] In-Reply-To: References: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> Message-ID: On Tue, 14 Jan 2025 19:15:05 GMT, Alexey Ivanov wrote: >> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: >> >> 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/jbs-jdk-bug-system.md line 236: > >> 234: * Enhancements that are pure cleanups: [[cleanup]{.jbs-label}](#cleanup) >> 235: * Project specific issues usually have their own labels as well >> 236: 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. > > Suggestion: > > 1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A) ensure 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 identified 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. > > > In ??a ?caused by? link should be added to 'B' or a ?causes? link to 'A'?, the word ?causes? needs the single-quotes to refer to the type of the link. (Also for consistency with other instances.) > > In ??that a fix _?causes?_ a change of behavior??, the word ?causes? should not have the quotes because the verb is used in its literal meaning rather being a type. > > I find it really hard to understand the last two sentences in this paragraph. ?This might be that extra work in another area was forgotten?? ? is ?was? missing here? The part after ?or?: if I understand correctly, _?the more common case?_ is a clarification, wrapping it the co... restructured a bit > src/guide/jbs-jdk-bug-system.md line 259: > >> 257: 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. >> 258: >> 259: There are the following link types: > > I suggest marking up the issue type with bold `**` if not with `
` 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. should now be consistent > src/guide/jbs-jdk-bug-system.md line 263: > >> 261: ?duplicate of` - Normally set automatically - see [Closing issues as duplicates] for more information >> 262: >> 263: ?backported by? - Normally set automatically when creating a backport with the ?More -> Create Backport? option > > Or when the backport is integrated? added a mention of Skara ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1924269016 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1924272318 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1924271535 From duke at openjdk.org Tue Jan 21 19:43:52 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 19:43:52 GMT Subject: RFR: Addition of a causes link type [v3] In-Reply-To: References: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> Message-ID: On Tue, 14 Jan 2025 19:40:18 GMT, Alexey Ivanov wrote: >> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: >> >> 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/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?) > > Suggestion: > > ?causes?/?caused by? - the ?causes? link implies a stronger relationship than ?relates to?. If an issue 'B' is traced back to the fix for issue 'A' then ?A causes B? (or ?B was caused by A?) > > Should it be ?B _is_ caused by A?? > > In the above text about regressions, issue A and B have dumb single quotes around them. This should be consistent here, therefore I added them in the suggestion. I think the past-tense makes sense, have added the quotes ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1924275155 From duke at openjdk.org Tue Jan 21 19:49:53 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 19:49:53 GMT Subject: RFR: Addition of a causes link type [v6] In-Reply-To: References: Message-ID: On Tue, 21 Jan 2025 19:41:04 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > restructured the 'managing regressions' section I don't think the fact that fix 'A' is backed out changes the 'A causes B' link itself, although B would be closed once the back-out happens but the link would remain. Lets see if David/Jesper have some suggestions ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2605600724 From duke at openjdk.org Tue Jan 21 19:53:27 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 21 Jan 2025 19:53:27 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: > 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 Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: resolved feedback ------------- Changes: - all: https://git.openjdk.org/guide/pull/139/files - new: https://git.openjdk.org/guide/pull/139/files/c41a42fb..8f803075 Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=139&range=06 - incr: https://webrevs.openjdk.org/?repo=guide&pr=139&range=05-06 Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.org/guide/pull/139.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/139/head:pull/139 PR: https://git.openjdk.org/guide/pull/139 From jwilhelm at openjdk.org Tue Jan 21 19:56:54 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Tue, 21 Jan 2025 19:56:54 GMT Subject: RFR: Addition of a causes link type [v6] In-Reply-To: References: Message-ID: On Tue, 21 Jan 2025 19:47:16 GMT, Roger Calnan wrote: > I don't think the fact that fix 'A' is backed out changes the 'A causes B' link itself, although B would be closed once the back-out happens but the link would remain. Lets see if David/Jesper have some suggestions I agree. This would be alternative 2 in step 3 of https://openjdk.org/guide/#backing-out-a-change - backing out the change is fixing the regression. We don't remove the links when issues are fixed. ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2605613559 From ihse at openjdk.org Tue Jan 21 21:22:50 2025 From: ihse at openjdk.org (Magnus Ihse Bursie) Date: Tue, 21 Jan 2025 21:22:50 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: On Tue, 21 Jan 2025 19:53:27 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > resolved feedback So if I have an old checkin A that caused a regression in e.g. a prior release that was not noticed at the time, and make a fix for it in B, but it is broken and is backed out in C, and then redone in D. A causes B, B causes C, and A causes D? ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2605762077 From dholmes at openjdk.org Wed Jan 22 06:45:51 2025 From: dholmes at openjdk.org (David Holmes) Date: Wed, 22 Jan 2025 06:45:51 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: On Tue, 21 Jan 2025 21:20:05 GMT, Magnus Ihse Bursie wrote: > B causes C I don't think it makes sense to have a backout issue be marked as "caused by" the original issue. I don't think that is the sense of "cause" this was intended to capture. ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2606420469 From ihse at openjdk.org Wed Jan 22 09:59:50 2025 From: ihse at openjdk.org (Magnus Ihse Bursie) Date: Wed, 22 Jan 2025 09:59:50 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: On Tue, 21 Jan 2025 19:53:27 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > resolved feedback Why not? I assume that one thing you want to capture is when backporting. So if B is broken, you definitely would want to know that it caused undesired behavior that was fixed by C. Or am I mistaken? ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2606781472 From aivanov at openjdk.org Wed Jan 22 13:08:52 2025 From: aivanov at openjdk.org (Alexey Ivanov) Date: Wed, 22 Jan 2025 13:08:52 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: On Wed, 22 Jan 2025 09:57:04 GMT, Magnus Ihse Bursie wrote: > Why not? I assume that one thing you want to capture is when backporting. So if B is broken, you definitely would want to know that it caused undesired behavior that was fixed by C. Or am I mistaken? I agree. The reason for backout is that the fix was broken, so C was caused by B. When backporting, B and C can be skipped, therefore a ?causes? link from A to D makes sense to me. ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2607201601 From ihse at openjdk.org Wed Jan 22 14:51:56 2025 From: ihse at openjdk.org (Magnus Ihse Bursie) Date: Wed, 22 Jan 2025 14:51:56 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: On Wed, 22 Jan 2025 13:06:23 GMT, Alexey Ivanov wrote: > When backporting, B and C can be skipped, therefore a ?causes? link from A to D makes sense to me. But that only makes sense once D is created. When creating B, the author genuinely believes that it fixes A. It is just that later on, B was found to be broken. Should we at that point go and remove the `causes` link for A? I'm not saying I have the right answer here, but I definitely think that whatever we come up with should be documented in the guide, since this is indeed a tricky scenario. ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2607426133 From aivanov at openjdk.org Wed Jan 22 15:01:56 2025 From: aivanov at openjdk.org (Alexey Ivanov) Date: Wed, 22 Jan 2025 15:01:56 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: On Wed, 22 Jan 2025 14:39:50 GMT, Magnus Ihse Bursie wrote: > > When backporting, B and C can be skipped, therefore a ?causes? link from A to D makes sense to me. > > But that only makes sense once D is created. When creating B, the author genuinely believes that it fixes A. It is just that later on, B was found to be broken. Should we at that point go and remove the `causes` link for A? I don't think we should. The relationship between A and B remains even after C is created, and after it's integrated, too. Additional comments could be added to clarify the relationships. However, the fact that B causes C and that C is a backout highlights that B isn't actually fixed. For this reason, D should be created as soon as it's clear B will be backed out ? at the same time when C is created. > I'm not saying I have the right answer here, but I definitely think that whatever we come up with should be documented in the guide, since this is indeed a tricky scenario. I don't know the right answer either. Yet I think A should have the _?causes?_ link to both B and D, possibly a _?relates to?_ link to C too. ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2607478137 From jwilhelm at openjdk.org Wed Jan 22 18:18:53 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Wed, 22 Jan 2025 18:18:53 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: On Tue, 21 Jan 2025 19:53:27 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > resolved feedback I don't see any scenario where we would delete a causes link unless it's added by mistake or some analysis later shows that the indicated bug isn't the cause. As always one must use common sense and do what's best in any edge case situation. To me it's clear that A causes B and D and I think it's preferred to keep the text short and readable over trying to explain every edge case out there. ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2607927948 From jwilhelm at openjdk.org Wed Jan 22 18:20:57 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Wed, 22 Jan 2025 18:20:57 GMT Subject: RFR: Note on Affected version Message-ID: Added a note on when to use the affected version field and did some other minor cleanups. ------------- Commit messages: - Changed wording - Note on Affected version Changes: https://git.openjdk.org/guide/pull/140/files Webrev: https://webrevs.openjdk.org/?repo=guide&pr=140&range=00 Stats: 10 lines in 2 files changed: 5 ins; 0 del; 5 mod Patch: https://git.openjdk.org/guide/pull/140.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/140/head:pull/140 PR: https://git.openjdk.org/guide/pull/140 From jwilhelm at openjdk.org Wed Jan 22 19:50:16 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Wed, 22 Jan 2025 19:50:16 GMT Subject: RFR: Note on Affected version [v2] In-Reply-To: References: Message-ID: <6ekwPeX5q7G3dW1pjae9QCj0yTfBjXKr2msgjBizeYg=.c22f8d20-0046-4463-be71-293fcbd79f2b@github.com> > Added a note on when to use the affected version field and did some other minor cleanups. Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: Bug must have affects version ------------- Changes: - all: https://git.openjdk.org/guide/pull/140/files - new: https://git.openjdk.org/guide/pull/140/files/a5abdd0f..94cb7c45 Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=140&range=01 - incr: https://webrevs.openjdk.org/?repo=guide&pr=140&range=00-01 Stats: 1 line in 1 file changed: 1 ins; 0 del; 0 mod Patch: https://git.openjdk.org/guide/pull/140.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/140/head:pull/140 PR: https://git.openjdk.org/guide/pull/140 From ihse at openjdk.org Thu Jan 23 00:36:59 2025 From: ihse at openjdk.org (Magnus Ihse Bursie) Date: Thu, 23 Jan 2025 00:36:59 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: On Tue, 21 Jan 2025 19:53:27 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > resolved feedback ... and B causes C, right? I don't think we need to explain every edge case, but I think the specific case of a backout could be served by being explicit in what to do in that situation. ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2608582817 From dholmes at openjdk.org Thu Jan 23 07:28:59 2025 From: dholmes at openjdk.org (David Holmes) Date: Thu, 23 Jan 2025 07:28:59 GMT Subject: RFR: Addition of a causes link type [v7] In-Reply-To: References: Message-ID: On Wed, 22 Jan 2025 13:06:23 GMT, Alexey Ivanov wrote: > Why not? I assume that one thing you want to capture is when backporting. So if B is broken, you definitely would want to know that it caused undesired behavior that was fixed by C. Or am I mistaken? First off if B is broken it should be Verified as Fix Failed and that is what tells backporters there is an issue. It then has a link to C (the backout) and a link to a REDO issue (potentially). These links are evident regardless of how the link is described. If we say that the Backout issue is caused by B then that would imply the REDO issue is also caused by B - they are both only necessary because B was broken. Are you proposing that as well? If so the Backout section of the guide also needs to reflect this. I understand that without B being broken there is no need for a Backout issue but that relationship is to me more specific than simply causal. Maybe we need a backed-out-by kind of link. ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2609044460 From jwilhelm at openjdk.org Thu Jan 23 17:57:14 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Thu, 23 Jan 2025 17:57:14 GMT Subject: RFR: Note on Affected version [v3] In-Reply-To: References: Message-ID: > Added a note on when to use the affected version field and did some other minor cleanups. > Also added some guidance around when to back out a change. Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: Clarifications around backing out ------------- Changes: - all: https://git.openjdk.org/guide/pull/140/files - new: https://git.openjdk.org/guide/pull/140/files/94cb7c45..69c17972 Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=140&range=02 - incr: https://webrevs.openjdk.org/?repo=guide&pr=140&range=01-02 Stats: 6 lines in 1 file changed: 4 ins; 0 del; 2 mod Patch: https://git.openjdk.org/guide/pull/140.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/140/head:pull/140 PR: https://git.openjdk.org/guide/pull/140 From duke at openjdk.org Thu Jan 23 18:46:07 2025 From: duke at openjdk.org (Roger Calnan) Date: Thu, 23 Jan 2025 18:46:07 GMT Subject: RFR: Addition of a causes link type [v3] In-Reply-To: References: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> Message-ID: On Tue, 14 Jan 2025 19:21:52 GMT, Alexey Ivanov wrote: >> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: >> >> 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/jbs-jdk-bug-system.md line 261: > >> 259: There are the following link types: >> 260: >> 261: ?duplicate of` - Normally set automatically - see [Closing issues as duplicates] for more information > > Suggestion: > > ?duplicate of? - Normally set automatically - see [Closing issues as duplicates] for more information > > > Does markdown support a definition list? Should we use HTML `
` and `
`, `
` tags to mark up the list? not at the moment it seems in commonmark - https://talk.commonmark.org/t/description-list/289/41 ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1927493862 From duke at openjdk.org Thu Jan 23 18:50:39 2025 From: duke at openjdk.org (Roger Calnan) Date: Thu, 23 Jan 2025 18:50:39 GMT Subject: RFR: Addition of a causes link type [v8] In-Reply-To: References: Message-ID: > 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 Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: resolved feedback ------------- Changes: - all: https://git.openjdk.org/guide/pull/139/files - new: https://git.openjdk.org/guide/pull/139/files/8f803075..1bb0f8b5 Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=139&range=07 - incr: https://webrevs.openjdk.org/?repo=guide&pr=139&range=06-07 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/guide/pull/139.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/139/head:pull/139 PR: https://git.openjdk.org/guide/pull/139 From duke at openjdk.org Thu Jan 23 19:31:02 2025 From: duke at openjdk.org (Roger Calnan) Date: Thu, 23 Jan 2025 19:31:02 GMT Subject: RFR: Addition of a causes link type [v8] In-Reply-To: References: Message-ID: On Thu, 23 Jan 2025 18:50:39 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > resolved feedback I'm not seeing that the last set of comments warrant any changes to the text Jesper handing over to you to review ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2610842251 From duke at openjdk.org Thu Jan 23 19:31:02 2025 From: duke at openjdk.org (Roger Calnan) Date: Thu, 23 Jan 2025 19:31:02 GMT Subject: RFR: Addition of a causes link type [v3] In-Reply-To: References: <5yn5Fn8w6p8w_LyIIdlwTDvURRTu3kkZYKp8gxrLG1s=.5e02020f-cdbd-4c51-aa37-63a223f2336e@github.com> Message-ID: On Tue, 14 Jan 2025 19:17:58 GMT, Alexey Ivanov wrote: >> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: >> >> 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/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 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. > > 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 (relates to). > > This should be enough as an example. The following list presents what link types are available and their meaning. updated ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1927574258 From iris at openjdk.org Thu Jan 23 19:46:01 2025 From: iris at openjdk.org (Iris Clark) Date: Thu, 23 Jan 2025 19:46:01 GMT Subject: RFR: Note on Affected version [v3] In-Reply-To: References: Message-ID: On Thu, 23 Jan 2025 17:57:14 GMT, Jesper Wilhelmsson wrote: >> Added a note on when to use the affected version field and did some other minor cleanups. >> Also added some guidance around when to back out a change. > > Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: > > Clarifications around backing out Marked as reviewed by iris (Reviewer). ------------- PR Review: https://git.openjdk.org/guide/pull/140#pullrequestreview-2570863305 From jwilhelm at openjdk.org Thu Jan 23 23:51:03 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Thu, 23 Jan 2025 23:51:03 GMT Subject: Integrated: Note on Affected version In-Reply-To: References: Message-ID: <_VbwunQU6EVdgBRlWz8Tu8-GjVPwoupzV9cUUw8uc_o=.8f75b09d-c4f3-4da4-bd8f-687740dba3f6@github.com> On Wed, 22 Jan 2025 18:15:41 GMT, Jesper Wilhelmsson wrote: > Added a note on when to use the affected version field and did some other minor cleanups. > Also added some guidance around when to back out a change. This pull request has now been integrated. Changeset: ca216eb8 Author: Jesper Wilhelmsson URL: https://git.openjdk.org/guide/commit/ca216eb86d9c3287b4c3e60878295774302329dc Stats: 17 lines in 3 files changed: 10 ins; 0 del; 7 mod Note on Affected version Reviewed-by: iris ------------- PR: https://git.openjdk.org/guide/pull/140 From jwilhelm at openjdk.org Fri Jan 24 00:06:01 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Fri, 24 Jan 2025 00:06:01 GMT Subject: RFR: Addition of a causes link type [v8] In-Reply-To: References: Message-ID: <-NsXrv3Vb3iS4cJ1NpInI1ZJ0M9co_XcpJtW2FBncx4=.63bcf359-75d8-4ca5-b6d4-cb91a67556c1@github.com> On Thu, 23 Jan 2025 18:50:39 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > resolved feedback Marked as reviewed by jwilhelm (Lead). ------------- PR Review: https://git.openjdk.org/guide/pull/139#pullrequestreview-2571367208 From aivanov at openjdk.org Fri Jan 24 14:54:01 2025 From: aivanov at openjdk.org (Alexey Ivanov) Date: Fri, 24 Jan 2025 14:54:01 GMT Subject: RFR: Addition of a causes link type [v8] In-Reply-To: References: Message-ID: <1CWF4MTLvmEygC2MpEFnI2U4Gfxv7gcpbsaqA9UM8T4=.c39e61e2-15ae-49c9-981c-9fbd4740156b@github.com> On Thu, 23 Jan 2025 18:50:39 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: > > resolved feedback Changes requested by aivanov (no project role). src/guide/backporting.md line 32: > 30: 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. > 31: > 32: Whenever looking to backport a fix the developer should look for both [blocked by]{.jbs-value} and [causes]{.jbs-value} links in order to understand the set of fixes that should be backported. Likewise, if A has already been backported the new [causes]{.jbs-value} linked issues will need to be assessed to see if it is important enough to be backported as well. Suggestion: Whenever looking to backport a fix, the developer should look for both [blocked by]{.jbs-value} and [causes]{.jbs-value} links in order to understand the set of fixes that should be backported. Likewise, if A has already been backported, the new [causes]{.jbs-value} linked issues will need to be assessed to see if it is important enough to be backported as well. src/guide/jbs-jdk-bug-system.md line 236: > 234: * Enhancements that are pure cleanups: [[cleanup]{.jbs-label}](#cleanup) > 235: * Project specific issues usually have their own labels as well > 236: 1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A) ensure that the label [[regression]{.jbs-label}](#regression) is added. Once it is known what fix caused the regression a [caused by]{.jbs-value} link should be added to 'B' or a [causes]{.jbs-value} link to 'A'. A [causes]{.jbs-value} link would also be added to A if the fix _causes_ a change of behavior (intentional or otherwise) or it is found after integration, that additional work needs to be done. If 'A' has been identified as well as a adding a [caused by]{.jbs-value} link to that issue, set the [Introduced in Build]{.jbs-field} and [Introduced in Version]{.jbs-field} fields of 'B', based on which release 'A' was fixed in. Do not add a [caused by]{.jbs-value} link if there was no specific product fix which _caused it_, for example, the addition of a test which finds an underlying problem should not be linked. Suggestion: 1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A), ensure that the label [[regression]{.jbs-label}](#regression) is added. Once it is known what fix caused the regression a [caused by]{.jbs-value} link should be added to 'B' or a [causes]{.jbs-value} link to 'A'. A [causes]{.jbs-value} link would also be added to 'A' if the fix _causes_ a change of behavior (intentional or otherwise) or it is found after integration, that additional work needs to be done. If 'A' has been identified as well as a adding a [caused by]{.jbs-value} link to that issue, set the [Introduced in Build]{.jbs-field} and [Introduced in Version]{.jbs-field} fields of 'B', based on which release 'A' was fixed in. Do not add a [caused by]{.jbs-value} link if there was no specific product fix which _caused it_, for example, the addition of a test which finds an underlying problem should not be linked. ?If 'A' has been identified as well as? ? identified as what? It looks as if something's missing? Would it be better to say, ?~~as well as~~ in addition to adding a [caused by]{.jbs-value} link to that issue, set the?? This way is clearer, in my opinion. I'd move the _Introduced in Version_ field before _Introduced in Build_ as the version is more important. src/guide/jbs-jdk-bug-system.md line 265: > 263: [backported by]{.jbs-value} - Normally set automatically when creating a backport with the ?More -> Create Backport? option, or by the Skara tooling > 264: > 265: [CSR for]{.jbs-value} - 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]{.jbs-value} - When creating a CSR with the ?More -> Create CSR? option, a link is automatically created between the main issue and the new CSR src/guide/jbs-jdk-bug-system.md line 269: > 267: [blocks]{.jbs-value} - 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]{.jbs-value} 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]{.jbs-value} - To avoid lots of relates links, the links should have some significance in relation to the cause and/or fix, for the current issue. In addition, relates links should not duplicate an existing [duplicated by]{.jbs-value}, [backported by]{.jbs-value}, [csr for]{.jbs-value} or [blocked by]{.jbs-value} link. In particular, it may be necessary to manually remove a [relates to]{.jbs-value} link if it is later added as a [duplicated by]{.jbs-value} or [caused by]{.jbs-value} link Suggestion: [relates to]{.jbs-value} - To avoid lots of relates links, the links should have some significance in relation to the cause and/or fix for the current issue. In addition, relates links should not duplicate an existing [duplicated by]{.jbs-value}, [backported by]{.jbs-value}, [csr for]{.jbs-value} or [blocked by]{.jbs-value} link. In particular, it may be necessary to manually remove a [relates to]{.jbs-value} link if it is later added as a [duplicated by]{.jbs-value} or [caused by]{.jbs-value} link The comma in the end of the first sentence is not need, is it? Should ?relates links? be replaced with ?relates to links? in the first two sentences? An italics could be used to mark them up to make it clear that these words refer to a type of the link. src/guide/jbs-jdk-bug-system.md line 271: > 269: [relates to]{.jbs-value} - To avoid lots of relates links, the links should have some significance in relation to the cause and/or fix, for the current issue. In addition, relates links should not duplicate an existing [duplicated by]{.jbs-value}, [backported by]{.jbs-value}, [csr for]{.jbs-value} or [blocked by]{.jbs-value} link. In particular, it may be necessary to manually remove a [relates to]{.jbs-value} link if it is later added as a [duplicated by]{.jbs-value} or [caused by]{.jbs-value} link > 270: > 271: [causes]{.jbs-value}/[caused by]{.jbs-value} - the causes link implies a stronger relationship than relates. If an issue 'B' can be traced back to the fix for issue 'A' then ?A causes B? (or ?B was caused by A?) Suggestion: [causes]{.jbs-value}/[caused by]{.jbs-value} - the _causes_ link implies a stronger relationship than _relates_. If an issue 'B' can be traced back to the fix for issue 'A' then ?A causes B? (or ?B is caused by A?) Mark up the type of the link; use the same tense for both *?A causes B?* and *?B is caused by A?*. ------------- PR Review: https://git.openjdk.org/guide/pull/139#pullrequestreview-2572812135 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928776000 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928785924 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928792116 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928798231 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1928804728 From duke at openjdk.org Mon Jan 27 16:27:18 2025 From: duke at openjdk.org (Roger Calnan) Date: Mon, 27 Jan 2025 16:27:18 GMT Subject: RFR: Addition of a causes link type [v9] In-Reply-To: References: Message-ID: > 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 Roger Calnan has updated the pull request incrementally with two additional commits since the last revision: - Update src/guide/jbs-jdk-bug-system.md Co-authored-by: Alexey Ivanov - Update src/guide/backporting.md Co-authored-by: Alexey Ivanov ------------- Changes: - all: https://git.openjdk.org/guide/pull/139/files - new: https://git.openjdk.org/guide/pull/139/files/1bb0f8b5..2cb52704 Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=139&range=08 - incr: https://webrevs.openjdk.org/?repo=guide&pr=139&range=07-08 Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.org/guide/pull/139.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/139/head:pull/139 PR: https://git.openjdk.org/guide/pull/139 From duke at openjdk.org Mon Jan 27 16:27:18 2025 From: duke at openjdk.org (Roger Calnan) Date: Mon, 27 Jan 2025 16:27:18 GMT Subject: RFR: Addition of a causes link type [v8] In-Reply-To: <1CWF4MTLvmEygC2MpEFnI2U4Gfxv7gcpbsaqA9UM8T4=.c39e61e2-15ae-49c9-981c-9fbd4740156b@github.com> References: <1CWF4MTLvmEygC2MpEFnI2U4Gfxv7gcpbsaqA9UM8T4=.c39e61e2-15ae-49c9-981c-9fbd4740156b@github.com> Message-ID: On Fri, 24 Jan 2025 14:49:20 GMT, Alexey Ivanov wrote: >> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: >> >> resolved feedback > > src/guide/jbs-jdk-bug-system.md line 269: > >> 267: [blocks]{.jbs-value} - 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]{.jbs-value} 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]{.jbs-value} - To avoid lots of relates links, the links should have some significance in relation to the cause and/or fix, for the current issue. In addition, relates links should not duplicate an existing [duplicated by]{.jbs-value}, [backported by]{.jbs-value}, [csr for]{.jbs-value} or [blocked by]{.jbs-value} link. In particular, it may be necessary to manually remove a [relates to]{.jbs-value} link if it is later added as a [duplicated by]{.jbs-value} or [caused by]{.jbs-value} link > > Suggestion: > > [relates to]{.jbs-value} - To avoid lots of relates links, the links should have some significance in relation to the cause and/or fix for the current issue. In addition, relates links should not duplicate an existing [duplicated by]{.jbs-value}, [backported by]{.jbs-value}, [csr for]{.jbs-value} or [blocked by]{.jbs-value} link. In particular, it may be necessary to manually remove a [relates to]{.jbs-value} link if it is later added as a [duplicated by]{.jbs-value} or [caused by]{.jbs-value} link > > > The comma in the end of the first sentence is not need, is it? > > Should ?relates links? be replaced with ?relates to links? in the first two sentences? An italics could be used to mark them up to make it clear that these words refer to a type of the link. the comma is fine, updated the first relates ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1930812956 From duke at openjdk.org Mon Jan 27 19:21:02 2025 From: duke at openjdk.org (Roger Calnan) Date: Mon, 27 Jan 2025 19:21:02 GMT Subject: RFR: Addition of a causes link type [v8] In-Reply-To: <1CWF4MTLvmEygC2MpEFnI2U4Gfxv7gcpbsaqA9UM8T4=.c39e61e2-15ae-49c9-981c-9fbd4740156b@github.com> References: <1CWF4MTLvmEygC2MpEFnI2U4Gfxv7gcpbsaqA9UM8T4=.c39e61e2-15ae-49c9-981c-9fbd4740156b@github.com> Message-ID: On Fri, 24 Jan 2025 14:40:38 GMT, Alexey Ivanov wrote: >> Roger Calnan has updated the pull request incrementally with one additional commit since the last revision: >> >> resolved feedback > > src/guide/jbs-jdk-bug-system.md line 236: > >> 234: * Enhancements that are pure cleanups: [[cleanup]{.jbs-label}](#cleanup) >> 235: * Project specific issues usually have their own labels as well >> 236: 1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A) ensure that the label [[regression]{.jbs-label}](#regression) is added. Once it is known what fix caused the regression a [caused by]{.jbs-value} link should be added to 'B' or a [causes]{.jbs-value} link to 'A'. A [causes]{.jbs-value} link would also be added to A if the fix _causes_ a change of behavior (intentional or otherwise) or it is found after integration, that additional work needs to be done. If 'A' has been identified as well as a adding a [caused by]{.jbs-value} link to that issue, set the [Introduced in Build]{.jbs-field} and [Introduced in Version]{.jbs-field} fields of 'B', based on which release 'A' was fixed in. Do not add a [caused by]{.jbs-value} link if there was no specific product fix which _caused it_, for example, the addition of a test which finds an underlying problem should not be linked. > > Suggestion: > > 1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A), ensure that the label [[regression]{.jbs-label}](#regression) is added. Once it is known what fix caused the regression a [caused by]{.jbs-value} link should be added to 'B' or a [causes]{.jbs-value} link to 'A'. A [causes]{.jbs-value} link would also be added to 'A' if the fix _causes_ a change of behavior (intentional or otherwise) or it is found after integration, that additional work needs to be done. If 'A' has been identified as well as a adding a [caused by]{.jbs-value} link to that issue, set the [Introduced in Build]{.jbs-field} and [Introduced in Version]{.jbs-field} fields of 'B', based on which release 'A' was fixed in. Do not add a [caused by]{.jbs-value} link if there was no specific product fix which _caused it_, for example, the addition of a test which finds an underlying problem should not be linked. > > > ?If 'A' has been identified as well as? ? identified as what? It looks as if something's missing? > Would it be better to say, ?~~as well as~~ in addition to adding a [caused by]{.jbs-value} link to that issue, set the?? > > This way is clearer, in my opinion. > > I'd move the _Introduced in Version_ field before _Introduced in Build_ as the version is more important. made the changes > src/guide/jbs-jdk-bug-system.md line 271: > >> 269: [relates to]{.jbs-value} - To avoid lots of relates links, the links should have some significance in relation to the cause and/or fix, for the current issue. In addition, relates links should not duplicate an existing [duplicated by]{.jbs-value}, [backported by]{.jbs-value}, [csr for]{.jbs-value} or [blocked by]{.jbs-value} link. In particular, it may be necessary to manually remove a [relates to]{.jbs-value} link if it is later added as a [duplicated by]{.jbs-value} or [caused by]{.jbs-value} link >> 270: >> 271: [causes]{.jbs-value}/[caused by]{.jbs-value} - the causes link implies a stronger relationship than relates. If an issue 'B' can be traced back to the fix for issue 'A' then ?A causes B? (or ?B was caused by A?) > > Suggestion: > > [causes]{.jbs-value}/[caused by]{.jbs-value} - the _causes_ link implies a stronger relationship than _relates_. If an issue 'B' can be traced back to the fix for issue 'A' then ?A causes B? (or ?B is caused by A?) > > > Mark up the type of the link; use the same tense for both *?A causes B?* and *?B is caused by A?*. done ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1931065495 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1931067798 From duke at openjdk.org Mon Jan 27 19:28:46 2025 From: duke at openjdk.org (Roger Calnan) Date: Mon, 27 Jan 2025 19:28:46 GMT Subject: RFR: Addition of a causes link type [v8] In-Reply-To: References: <1CWF4MTLvmEygC2MpEFnI2U4Gfxv7gcpbsaqA9UM8T4=.c39e61e2-15ae-49c9-981c-9fbd4740156b@github.com> Message-ID: <-rD7SeBNG3eq6gp2EearvgOzUCUH2jtroGC63o44Tns=.7c7d2d6b-f63b-4b40-ac76-a29d06eb591d@github.com> On Mon, 27 Jan 2025 19:15:29 GMT, Roger Calnan wrote: >> src/guide/jbs-jdk-bug-system.md line 236: >> >>> 234: * Enhancements that are pure cleanups: [[cleanup]{.jbs-label}](#cleanup) >>> 235: * Project specific issues usually have their own labels as well >>> 236: 1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A) ensure that the label [[regression]{.jbs-label}](#regression) is added. Once it is known what fix caused the regression a [caused by]{.jbs-value} link should be added to 'B' or a [causes]{.jbs-value} link to 'A'. A [causes]{.jbs-value} link would also be added to A if the fix _causes_ a change of behavior (intentional or otherwise) or it is found after integration, that additional work needs to be done. If 'A' has been identified as well as a adding a [caused by]{.jbs-value} link to that issue, set the [Introduced in Build]{.jbs-field} and [Introduced in Version]{.jbs-field} fields of 'B', based on which release 'A' was fixed in. Do not add a [caused by]{.jbs-value} link if there was no specific product fix which _caused it_, for example, the addition of a test which finds an underlying problem should not be linked. >> >> Suggestion: >> >> 1. Managing regressions - for a bug (B) where behavior has _incorrectly_ changed from a previous fix (A), ensure that the label [[regression]{.jbs-label}](#regression) is added. Once it is known what fix caused the regression a [caused by]{.jbs-value} link should be added to 'B' or a [causes]{.jbs-value} link to 'A'. A [causes]{.jbs-value} link would also be added to 'A' if the fix _causes_ a change of behavior (intentional or otherwise) or it is found after integration, that additional work needs to be done. If 'A' has been identified as well as a adding a [caused by]{.jbs-value} link to that issue, set the [Introduced in Build]{.jbs-field} and [Introduced in Version]{.jbs-field} fields of 'B', based on which release 'A' was fixed in. Do not add a [caused by]{.jbs-value} link if there was no specific product fix which _caused it_, for example, the addition of a test which finds an underlying problem should not be linked. >> >> >> ?If 'A' has been identified as well as? ? identified as what? It looks as if something's missing? >> Would it be better to say, ?~~as well as~~ in addition to adding a [caused by]{.jbs-value} link to that issue, set the?? >> >> This way is clearer, in my opinion. >> >> I'd move the _Introduced in Version_ field before _Introduced in Build_ as the version is more important. > > made the changes done ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1931073880 From duke at openjdk.org Mon Jan 27 19:28:43 2025 From: duke at openjdk.org (Roger Calnan) Date: Mon, 27 Jan 2025 19:28:43 GMT Subject: RFR: Addition of a causes link type [v10] In-Reply-To: References: Message-ID: > 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 Roger Calnan has updated the pull request incrementally with three additional commits since the last revision: - removed trailing space - resolved feedback - Update full name ------------- Changes: - all: https://git.openjdk.org/guide/pull/139/files - new: https://git.openjdk.org/guide/pull/139/files/2cb52704..fa5f66c1 Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=139&range=09 - incr: https://webrevs.openjdk.org/?repo=guide&pr=139&range=08-09 Stats: 7 lines in 2 files changed: 2 ins; 2 del; 3 mod Patch: https://git.openjdk.org/guide/pull/139.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/139/head:pull/139 PR: https://git.openjdk.org/guide/pull/139 From duke at openjdk.org Mon Jan 27 19:28:44 2025 From: duke at openjdk.org (Roger Calnan) Date: Mon, 27 Jan 2025 19:28:44 GMT Subject: RFR: Addition of a causes link type [v9] In-Reply-To: References: Message-ID: On Mon, 27 Jan 2025 16:27:18 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with two additional commits since the last revision: > > - Update src/guide/jbs-jdk-bug-system.md > > Co-authored-by: Alexey Ivanov > - Update src/guide/backporting.md > > Co-authored-by: Alexey Ivanov Jesper, as discussed I moved the order of the paragraphs in "Backporting multiple related changes" ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2616699138 From jwilhelm at openjdk.org Tue Jan 28 18:11:10 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Tue, 28 Jan 2025 18:11:10 GMT Subject: RFR: Describe in JBS before PR Message-ID: Added a note to remind to have a description in JBS before creating a PR. ------------- Commit messages: - Describe in JBS before PR Changes: https://git.openjdk.org/guide/pull/141/files Webrev: https://webrevs.openjdk.org/?repo=guide&pr=141&range=00 Stats: 4 lines in 1 file changed: 4 ins; 0 del; 0 mod Patch: https://git.openjdk.org/guide/pull/141.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/141/head:pull/141 PR: https://git.openjdk.org/guide/pull/141 From jwilhelm at openjdk.org Tue Jan 28 18:17:03 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Tue, 28 Jan 2025 18:17:03 GMT Subject: RFR: Addition of a causes link type [v10] In-Reply-To: References: Message-ID: On Mon, 27 Jan 2025 19:28:43 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with three additional commits since the last revision: > > - removed trailing space > - resolved feedback > - Update full name Marked as reviewed by jwilhelm (Lead). ------------- PR Review: https://git.openjdk.org/guide/pull/139#pullrequestreview-2579077603 From duke at openjdk.org Tue Jan 28 18:28:00 2025 From: duke at openjdk.org (duke) Date: Tue, 28 Jan 2025 18:28:00 GMT Subject: RFR: Addition of a causes link type [v10] In-Reply-To: References: Message-ID: On Mon, 27 Jan 2025 19:28:43 GMT, Roger Calnan 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 > > Roger Calnan has updated the pull request incrementally with three additional commits since the last revision: > > - removed trailing space > - resolved feedback > - Update full name @calnan Your change (at version fa5f66c1774c5e508dc14a2c18d80389ea1d2247) is now ready to be sponsored by a Committer. ------------- PR Comment: https://git.openjdk.org/guide/pull/139#issuecomment-2619755138 From iris at openjdk.org Tue Jan 28 18:41:05 2025 From: iris at openjdk.org (Iris Clark) Date: Tue, 28 Jan 2025 18:41:05 GMT Subject: RFR: Describe in JBS before PR In-Reply-To: References: Message-ID: On Tue, 28 Jan 2025 18:06:41 GMT, Jesper Wilhelmsson wrote: > Added a note to remind to have a description in JBS before creating a PR. Marked as reviewed by iris (Reviewer). ------------- PR Review: https://git.openjdk.org/guide/pull/141#pullrequestreview-2579128762 From duke at openjdk.org Tue Jan 28 19:23:11 2025 From: duke at openjdk.org (Roger Calnan) Date: Tue, 28 Jan 2025 19:23:11 GMT Subject: Integrated: Addition of a causes link type In-Reply-To: References: Message-ID: On Tue, 3 Dec 2024 22:59:53 GMT, Roger Calnan 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 This pull request has now been integrated. Changeset: 5ce900fb Author: roger_calnan Committer: Jesper Wilhelmsson URL: https://git.openjdk.org/guide/commit/5ce900fb43f0e5f3732ec03a719c06292e14942e Stats: 23 lines in 2 files changed: 21 ins; 2 del; 0 mod Addition of a causes link type Reviewed-by: jwilhelm ------------- PR: https://git.openjdk.org/guide/pull/139 From jwilhelm at openjdk.org Wed Jan 29 21:35:59 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Wed, 29 Jan 2025 21:35:59 GMT Subject: Integrated: Describe in JBS before PR In-Reply-To: References: Message-ID: On Tue, 28 Jan 2025 18:06:41 GMT, Jesper Wilhelmsson wrote: > Added a note to remind to have a description in JBS before creating a PR. This pull request has now been integrated. Changeset: ef416dd4 Author: Jesper Wilhelmsson URL: https://git.openjdk.org/guide/commit/ef416dd4e54e9ab46ce7e4f306c5df3d1f66cb43 Stats: 4 lines in 1 file changed: 4 ins; 0 del; 0 mod Describe in JBS before PR Reviewed-by: iris ------------- PR: https://git.openjdk.org/guide/pull/141