RFR: Addition of a causes link type [v3]

Tue Jan 14 19:45:57 UTC 2025

On Tue, 14 Jan 2025 18:03:18 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 - 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 `<dt>` 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 `<dl>` and `<dt>`, `<dd>` 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