Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

docs: handling-regressions.rst: recommend using "Closes:" tags

Update the handling-regressions guide to recommend using "Closes:" tags
rather than "Link:" when referencing fixed reports. The latter was used
originally but now is only recommended when the given patch only fixes
part of the issue, as described in submitting-patches. Briefly mention
that and also note that regzbot currently doesn't make a distinction.

Also fix a typo.

Acked-by: Thorsten Leemhuis <linux@leemhuis.info>
Signed-off-by: Karel Balej <balejk@matfyz.cz>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240513084145.2460-1-balejk@matfyz.cz

authored by

Karel Balej and committed by
Jonathan Corbet
b80103a2 1a0e2cd9

+18 -12
+18 -12
Documentation/process/handling-regressions.rst
··· 40 40 #regzbot from: Some N. Ice Human <some.human@example.com> 41 41 #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 42 42 43 - #. When submitting fixes for regressions, add "Link:" tags to the patch 43 + #. When submitting fixes for regressions, add "Closes:" tags to the patch 44 44 description pointing to all places where the issue was reported, as 45 45 mandated by Documentation/process/submitting-patches.rst and 46 - :ref:`Documentation/process/5.Posting.rst <development_posting>`. 46 + :ref:`Documentation/process/5.Posting.rst <development_posting>`. If you are 47 + only fixing part of the issue that caused the regression, you may use 48 + "Link:" tags instead. regzbot currently makes no distinction between the 49 + two. 47 50 48 51 #. Try to fix regressions quickly once the culprit has been identified; fixes 49 52 for most regressions should be merged within two weeks, but some need to be ··· 94 91 Note the caret (^) before the "introduced": it tells regzbot to treat the 95 92 parent mail (the one you reply to) as the initial report for the regression 96 93 you want to see tracked; that's important, as regzbot will later look out 97 - for patches with "Link:" tags pointing to the report in the archives on 94 + for patches with "Closes:" tags pointing to the report in the archives on 98 95 lore.kernel.org. 99 96 100 - * When forwarding a regressions reported to a bug tracker, include a paragraph 97 + * When forwarding a regression reported to a bug tracker, include a paragraph 101 98 with these regzbot commands:: 102 99 103 100 #regzbot introduced: 1f2e3d4c5b6a ··· 105 102 #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 106 103 107 104 Regzbot will then automatically associate patches with the report that 108 - contain "Link:" tags pointing to your mail or the mentioned ticket. 105 + contain "Closes:" tags pointing to your mail or the mentioned ticket. 109 106 110 107 What's important when fixing regressions 111 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ··· 115 112 :ref:`Documentation/process/5.Posting.rst <development_posting>`, and 116 113 Documentation/process/stable-kernel-rules.rst already explain in more detail: 117 114 118 - * Point to all places where the issue was reported using "Link:" tags:: 115 + * Point to all places where the issue was reported using "Closes:" tags:: 119 116 120 - Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ 121 - Link: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890 117 + Closes: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ 118 + Closes: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890 119 + 120 + If you are only fixing part of the issue, you may use "Link:" instead as 121 + described in the first document mentioned above. regzbot currently treats 122 + both of these equivalently and considers the linked reports as resolved. 122 123 123 124 * Add a "Fixes:" tag to specify the commit causing the regression. 124 125 ··· 133 126 these tags are of great value for everyone (you included) that might be looking 134 127 into the issue weeks, months, or years later. These tags are also crucial for 135 128 tools and scripts used by other kernel developers or Linux distributions; one of 136 - these tools is regzbot, which heavily relies on the "Link:" tags to associate 129 + these tools is regzbot, which heavily relies on the "Closes:" tags to associate 137 130 reports for regression with changes resolving them. 138 131 139 132 Expectations and best practices for fixing regressions ··· 333 326 334 327 The bot watches for replies to reports of tracked regressions. Additionally, 335 328 it's looking out for posted or committed patches referencing such reports 336 - with "Link:" tags; replies to such patch postings are tracked as well. 329 + with "Closes:" tags; replies to such patch postings are tracked as well. 337 330 Combined this data provides good insights into the current state of the fixing 338 331 process. 339 332 ··· 345 338 346 339 For developers there normally is no extra work involved, they just need to make 347 340 sure to do something that was expected long before regzbot came to light: add 348 - "Link:" tags to the patch description pointing to all reports about the issue 349 - fixed. 341 + links to the patch description pointing to all reports about the issue fixed. 350 342 351 343 Do I have to use regzbot? 352 344 ~~~~~~~~~~~~~~~~~~~~~~~~~