lkml.org 
[lkml]   [2018]   [Nov]   [8]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [patch 2/2] Documentation/process: Add tip tree handbook

* Thomas Gleixner <tglx@linutronix.de> wrote:

> + - Fixes: 12char-SHA1 ("sub/sys: Original subject line")
> +
> + A Fixes tag should be added even for changes which do not need to be
> + backported to stable kernels, i.e. when addressing a recently introduced
> + issue which only affects tip or the current head of mainline. These tags
> + are helpful to identify the original commit and are much more valuable
> + than prominently mentioning the commit which introduced a problem in the
> + text of the changelog itself because they can be automatically
> + extracted.
> +
> + The following example illustrates the difference::
> +
> + Commit
> +
> + abcdef012345678 ("x86/xxx: Replace foo with bar")
> +
> + left an unused instance of variable foo around. Remove it.
> +
> + Signed-off-by: J.Dev <j.dev@mail>
> +
> + Please say instead::
> +
> + The recent replacement of foo with bar left an unused instance of
> + variable foo around. Remove it.
> +
> + Fixes: abcdef012345678 ("x86/xxx: Replace foo with bar")
> + Signed-off-by: J.Dev <j.dev@mail>

Let me extend this policy element, I frequently write out commits in the
changelog itself *as well*, because that's where I utilize it myself when
reading other people's changelogs.

I.e. I would convert this:

The recent replacement of left with right left an unused instance of
variable left around. Remove it.

Fixes: abcdef012345678 ("x86/xxx: Replace 'left' with 'right')
Signed-off-by: J.Dev <j.dev@mail>

... to the following form:

Two years ago the following commit:

abcdef012345678 ("x86/xxx: Replace foo with bar")

... left an unused instance of the variable 'left' around. Remove it.

Fixes: abcdef012345678 ("x86/xxx: Replace 'left' with 'right')
Signed-off-by: J.Dev <j.dev@mail>

This changelog style, while more verbose, has a couple of advantages:

- It's a bad practice to force the reader to go the tags sections, fish
out a commit ID, just to be able to see the original commit.
Especially with longer changelogs and with changelogs mentioning
multiple source commits in-lining the commit ID is useful.

- Also note how this style allows for human-readable time information to
be inserted - which can be important to backporters. While an unused
variable warning might not be backported, in other cases the time
information can be useful in prioritizing the backporting.

- Also note another pet peeve of mine: the quotation marks around the
variable names 'left' and 'right'. I changed the variable names to
English words that are ambiguous in free-flowing changelog text, just
to illustrate how important it can be to escape them for better
readability.

The 'Fixes' tag is mainly a standard tag that backporter tooling can
search for - otherwise for human readers the in-line explanation is more
useful.

I really trivial cases the inlining can be skipped and only a 'Fixes' tag
is perfectly sufficient.

Thanks,

Ingo

\
 
 \ /
  Last update: 2018-11-08 08:31    [W:0.163 / U:1.180 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site