Messages in this thread | | | Date | Thu, 8 Nov 2018 08:30:51 +0100 | From | Ingo Molnar <> | Subject | Re: [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
| |