From duke at openjdk.org Tue Dec 3 23:04:14 2024 From: duke at openjdk.org (Roger Calnan) Date: Tue, 3 Dec 2024 23:04:14 GMT Subject: RFR: Addition of a causes link type 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 ------------- Commit messages: - draft of an update of guide to cover the potential addition of a causes link type Changes: https://git.openjdk.org/guide/pull/139/files Webrev: https://webrevs.openjdk.org/?repo=guide&pr=139&range=00 Stats: 19 lines in 1 file changed: 18 ins; 1 del; 0 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 dholmes at openjdk.org Wed Dec 4 02:47:51 2024 From: dholmes at openjdk.org (David Holmes) Date: Wed, 4 Dec 2024 02:47:51 GMT Subject: RFR: 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 NIce to see such a section being added - and I've missed a "caused-by" link for many years (why did we not have it from day one?). A few suggestions however. Thanks 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 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. Linking can occur at any stage of an issue's lifecycle: when it is filed, when it is triaged, when it is being worked upon, or when it is being closed. 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; or when a Backport or CSR request is created; or when closing as a duplicate of another issue. src/guide/jbs-jdk-bug-system.md line 261: > 259: There are the following link types: > 260: > 261: ?duplicate of` - See [Closing issues as duplicates] for more information. Suggestion: ?duplicate of` - Normally set automatically - see [Closing issues as duplicates] for more information. src/guide/jbs-jdk-bug-system.md line 263: > 261: ?duplicate of` - See [Closing issues as duplicates] for more information. > 262: > 263: ?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 Suggestion: ?backported by? - Normally set automatically when creating a backport with the ?More -> Create Backport? option src/guide/jbs-jdk-bug-system.md line 265: > 263: ?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 > 264: > 265: ?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 Suggestion: ?CSR for? - Normally created automatically when creating a CSR with the ?More -> Create CSR? option a link src/guide/jbs-jdk-bug-system.md line 267: > 265: ?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 > 266: > 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] Suggestion: ?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] 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?) 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 impor tant 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. ------------- PR Review: https://git.openjdk.org/guide/pull/139#pullrequestreview-2477157262 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868628419 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868628759 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868629214 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868629653 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868631087 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868632292 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868635914 From dholmes at openjdk.org Wed Dec 4 02:47:51 2024 From: dholmes at openjdk.org (David Holmes) Date: Wed, 4 Dec 2024 02:47:51 GMT Subject: RFR: Addition of a causes link type In-Reply-To: References: Message-ID: On Wed, 4 Dec 2024 02:36:11 GMT, David Holmes 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 > > 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 impo rtant 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. ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868637018 From duke at openjdk.org Wed Dec 4 03:32:24 2024 From: duke at openjdk.org (Roger Calnan) Date: Wed, 4 Dec 2024 03:32:24 GMT Subject: RFR: Addition of a causes link type [v2] 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/db4e414e..6acfc53c Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=139&range=01 - incr: https://webrevs.openjdk.org/?repo=guide&pr=139&range=00-01 Stats: 4 lines in 1 file changed: 0 ins; 0 del; 4 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 Wed Dec 4 03:32:25 2024 From: duke at openjdk.org (Roger Calnan) Date: Wed, 4 Dec 2024 03:32:25 GMT Subject: RFR: Addition of a causes link type [v2] In-Reply-To: References: Message-ID: On Wed, 4 Dec 2024 02:24:43 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 257: > >> 255: ### Linking Issues >> 256: >> 257: 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. > > Linking can occur at any stage of an issue's lifecycle: when it is filed, when it is triaged, when it is being worked upon, or when it is being closed. 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; or when a Backport or CSR request is created; or when closing as a duplicate of another issue. done I think we may want to emphasis that backports should not be created by hand - but perhaps that should be in the backport section - I'll look at that along with your last point > src/guide/jbs-jdk-bug-system.md line 261: > >> 259: There are the following link types: >> 260: >> 261: ?duplicate of` - See [Closing issues as duplicates] for more information. > > Suggestion: > > ?duplicate of` - Normally set automatically - see [Closing issues as duplicates] for more information. done > src/guide/jbs-jdk-bug-system.md line 263: > >> 261: ?duplicate of` - See [Closing issues as duplicates] for more information. >> 262: >> 263: ?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 > > Suggestion: > > ?backported by? - Normally set automatically when creating a backport with the ?More -> Create Backport? option done > src/guide/jbs-jdk-bug-system.md line 265: > >> 263: ?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 >> 264: >> 265: ?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 > > Suggestion: > > ?CSR for? - Normally created automatically when creating a CSR with the ?More -> Create CSR? option a link done > src/guide/jbs-jdk-bug-system.md line 267: > >> 265: ?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 >> 266: >> 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] > > Suggestion: > > ?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] done ------------- PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868668650 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868669666 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868668717 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868668768 PR Review Comment: https://git.openjdk.org/guide/pull/139#discussion_r1868668907 From jwilhelm at openjdk.org Wed Dec 4 17:55:00 2024 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Wed, 4 Dec 2024 17:55:00 GMT Subject: Integrated: GTest docs moved In-Reply-To: References: Message-ID: On Wed, 20 Nov 2024 17:47:19 GMT, Jesper Wilhelmsson wrote: > Updated links to GTest Docs. This pull request has now been integrated. Changeset: 8098c227 Author: Jesper Wilhelmsson URL: https://git.openjdk.org/guide/commit/8098c2276c11863a2e3a391bb09e162be4f6adb1 Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod GTest docs moved Reviewed-by: iris ------------- PR: https://git.openjdk.org/guide/pull/138 From dholmes at openjdk.org Mon Dec 9 05:05:51 2024 From: dholmes at openjdk.org (David Holmes) Date: Mon, 9 Dec 2024 05:05:51 GMT Subject: RFR: Addition of a causes link type [v2] In-Reply-To: References: Message-ID: On Wed, 4 Dec 2024 03:32:24 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 Thanks for updates. ------------- PR Review: https://git.openjdk.org/guide/pull/139#pullrequestreview-2487734335