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: <BD6bhIO_qdHy9ABAT1JfacPbLUmu1GgOPFmcYAN9VjE=.ddebf0ec-b2d0-4f92-be5c-b92c02a339e5@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

-------------

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: <BD6bhIO_qdHy9ABAT1JfacPbLUmu1GgOPFmcYAN9VjE=.ddebf0ec-b2d0-4f92-be5c-b92c02a339e5@github.com>
References: <BD6bhIO_qdHy9ABAT1JfacPbLUmu1GgOPFmcYAN9VjE=.ddebf0ec-b2d0-4f92-be5c-b92c02a339e5@github.com>
Message-ID: <aH8XNLhiUTNAcAf9XKnAaaqEpBerCdhmcxoaoINNVf0=.520845e2-9e63-4ca9-8ee9-7c01c5883416@github.com>

On Tue, 3 Dec 2024 22:59:53 GMT, Roger Calnan <duke at openjdk.org> 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: <aH8XNLhiUTNAcAf9XKnAaaqEpBerCdhmcxoaoINNVf0=.520845e2-9e63-4ca9-8ee9-7c01c5883416@github.com>
References: <BD6bhIO_qdHy9ABAT1JfacPbLUmu1GgOPFmcYAN9VjE=.ddebf0ec-b2d0-4f92-be5c-b92c02a339e5@github.com>
 <aH8XNLhiUTNAcAf9XKnAaaqEpBerCdhmcxoaoINNVf0=.520845e2-9e63-4ca9-8ee9-7c01c5883416@github.com>
Message-ID: <gjovafK6CFoG99J3oYYskrMdb4TIiB7n3rf8fQBUYek=.a126b761-0ac0-4322-9fb9-7ef27b6b3a49@github.com>

On Wed, 4 Dec 2024 02:36:11 GMT, David Holmes <dholmes at openjdk.org> 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: <BD6bhIO_qdHy9ABAT1JfacPbLUmu1GgOPFmcYAN9VjE=.ddebf0ec-b2d0-4f92-be5c-b92c02a339e5@github.com>
References: <BD6bhIO_qdHy9ABAT1JfacPbLUmu1GgOPFmcYAN9VjE=.ddebf0ec-b2d0-4f92-be5c-b92c02a339e5@github.com>
Message-ID: <wDDY7EjjUCSDm53stI79_8JTFsehsA6wwnsIqDSFLcY=.207588ed-b703-47d8-a915-0fd978b73f63@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

-------------

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: <aH8XNLhiUTNAcAf9XKnAaaqEpBerCdhmcxoaoINNVf0=.520845e2-9e63-4ca9-8ee9-7c01c5883416@github.com>
References: <BD6bhIO_qdHy9ABAT1JfacPbLUmu1GgOPFmcYAN9VjE=.ddebf0ec-b2d0-4f92-be5c-b92c02a339e5@github.com>
 <aH8XNLhiUTNAcAf9XKnAaaqEpBerCdhmcxoaoINNVf0=.520845e2-9e63-4ca9-8ee9-7c01c5883416@github.com>
Message-ID: <XLY-NbLdDMQjZO5VG1ftNOsCRFBGFBU5Cc85UbXUG8E=.c2f74fd5-9000-47cd-903b-894bebf6db6a@github.com>

On Wed, 4 Dec 2024 02:24:43 GMT, David Holmes <dholmes at openjdk.org> 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: <oaabLLqNNGspu6xAJoxqEnncLK-mCugPfQT5MUIPfhQ=.dcce7d7b-9d97-4c9f-b9e1-b4f810f66402@github.com>
References: <oaabLLqNNGspu6xAJoxqEnncLK-mCugPfQT5MUIPfhQ=.dcce7d7b-9d97-4c9f-b9e1-b4f810f66402@github.com>
Message-ID: <BHWVuf5YAhXs1DT2LoOv55xszVsYdXQmsEPYrBFAb2w=.d82359dd-c135-401f-a88b-c48bf81fd94a@github.com>

On Wed, 20 Nov 2024 17:47:19 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> Updated links to GTest Docs.

This pull request has now been integrated.

Changeset: 8098c227
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
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: <wDDY7EjjUCSDm53stI79_8JTFsehsA6wwnsIqDSFLcY=.207588ed-b703-47d8-a915-0fd978b73f63@github.com>
References: <BD6bhIO_qdHy9ABAT1JfacPbLUmu1GgOPFmcYAN9VjE=.ddebf0ec-b2d0-4f92-be5c-b92c02a339e5@github.com>
 <wDDY7EjjUCSDm53stI79_8JTFsehsA6wwnsIqDSFLcY=.207588ed-b703-47d8-a915-0fd978b73f63@github.com>
Message-ID: <c5Ssr-vD_XHuCWUnZdv0_9Ygvmul54upuovLdAaxkhc=.f1a26a66-3d76-4dc2-a855-4629d350dd55@github.com>

On Wed, 4 Dec 2024 03:32:24 GMT, Roger Calnan <duke at openjdk.org> 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