RFR: Addition of a causes link type [v3]

[Roger Calnan]

On Tue, 14 Jan 2025 19:15:05 GMT, Alexey Ivanov <aivanov at openjdk.org> 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 `<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.

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