From: Ingo Molnar <mingo@kernel.org>
To: Thomas Gleixner <tglx@linutronix.de>
Cc: LKML <linux-kernel@vger.kernel.org>,
x86@kernel.org, Peter Zijlstra <peterz@infradead.org>,
Paul McKenney <paulmck@linux.vnet.ibm.com>,
John Stultz <john.stultz@linaro.org>,
Arnaldo Carvalho de Melo <acme@redhat.com>,
Frederic Weisbecker <frederic@kernel.org>,
Jonathan Corbet <corbet@lwn.net>,
Andy Lutomirski <luto@kernel.org>,
Marc Zyngier <marc.zyngier@arm.com>,
Daniel Lezcano <daniel.lezcano@linaro.org>,
Dave Hansen <dave.hansen@linux.intel.com>,
Ard Biesheuvel <ard.biesheuvel@linaro.org>,
Will Deacon <will.deacon@arm.com>,
Mark Brown <broonie@kernel.org>,
Dan Williams <dan.j.williams@intel.com>
Subject: Re: [patch 2/2] Documentation/process: Add tip tree handbook
Date: Thu, 8 Nov 2018 08:30:51 +0100 [thread overview]
Message-ID: <20181108073051.GC20032@gmail.com> (raw)
In-Reply-To: <20181107171149.165693799@linutronix.de>
* 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
next prev parent reply other threads:[~2018-11-08 7:30 UTC|newest]
Thread overview: 51+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-11-07 17:10 [patch 0/2] Documentation/process: Add subsystem/tree handbook Thomas Gleixner
2018-11-07 17:10 ` [patch 1/2] Documentation/process: Add maintainer handbooks section Thomas Gleixner
2018-11-07 17:10 ` [patch 2/2] Documentation/process: Add tip tree handbook Thomas Gleixner
2018-11-07 17:44 ` Thomas Gleixner
2018-11-07 19:57 ` Paul E. McKenney
2018-11-07 19:38 ` Paul E. McKenney
2018-11-08 7:05 ` Ingo Molnar
2018-11-08 7:14 ` Ingo Molnar
2018-11-08 7:19 ` Ingo Molnar
2018-11-08 7:30 ` Ingo Molnar [this message]
2018-11-08 7:40 ` Ingo Molnar
2018-11-08 9:12 ` Peter Zijlstra
2018-11-08 11:05 ` Greg Kroah-Hartman
2018-11-08 17:19 ` Dan Williams
2018-11-08 17:24 ` Borislav Petkov
2018-11-08 17:40 ` Paul E. McKenney
2018-11-08 19:58 ` Thomas Gleixner
2018-11-08 20:05 ` Paul E. McKenney
2018-11-08 21:06 ` Greg KH
2018-11-08 21:08 ` Greg KH
2018-11-08 22:38 ` Thomas Gleixner
2018-11-08 20:14 ` Theodore Y. Ts'o
2018-11-08 20:22 ` Thomas Gleixner
2018-11-08 21:04 ` Greg KH
2018-11-08 22:19 ` Theodore Y. Ts'o
2018-11-08 22:33 ` Greg KH
2018-11-08 22:56 ` Dan Williams
2018-11-08 7:46 ` Ingo Molnar
2018-11-08 8:04 ` Ingo Molnar
2018-11-08 8:13 ` Ingo Molnar
2018-11-08 8:18 ` Ingo Molnar
2018-11-08 8:30 ` Ingo Molnar
2018-11-07 19:48 ` [patch 0/2] Documentation/process: Add subsystem/tree handbook Jonathan Corbet
2018-11-07 19:58 ` Dan Williams
2018-11-07 20:51 ` Thomas Gleixner
2018-11-08 14:49 ` Jonathan Corbet
2018-11-08 15:05 ` Peter Zijlstra
2018-11-08 15:19 ` Jonathan Corbet
2018-11-08 16:05 ` Paul E. McKenney
2018-11-08 16:21 ` Theodore Y. Ts'o
2018-11-08 16:32 ` Mark Brown
2018-11-08 17:32 ` Dan Williams
2018-11-13 23:15 ` Mark Brown
2018-11-08 16:33 ` Jonathan Corbet
2018-11-08 19:46 ` Theodore Y. Ts'o
2018-11-08 15:49 ` Thomas Gleixner
2020-12-17 15:05 ` Borislav Petkov
2020-12-17 17:53 ` Jonathan Corbet
2020-12-17 17:58 ` Borislav Petkov
2018-11-12 5:52 ` Ingo Molnar
2021-09-13 15:39 [PATCH 0/2] doc: Add tip maintainer's handbook Borislav Petkov
2021-09-13 15:39 ` [PATCH 2/2] Documentation/process: Add tip tree handbook Borislav Petkov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20181108073051.GC20032@gmail.com \
--to=mingo@kernel.org \
--cc=acme@redhat.com \
--cc=ard.biesheuvel@linaro.org \
--cc=broonie@kernel.org \
--cc=corbet@lwn.net \
--cc=dan.j.williams@intel.com \
--cc=daniel.lezcano@linaro.org \
--cc=dave.hansen@linux.intel.com \
--cc=frederic@kernel.org \
--cc=john.stultz@linaro.org \
--cc=linux-kernel@vger.kernel.org \
--cc=luto@kernel.org \
--cc=marc.zyngier@arm.com \
--cc=paulmck@linux.vnet.ibm.com \
--cc=peterz@infradead.org \
--cc=tglx@linutronix.de \
--cc=will.deacon@arm.com \
--cc=x86@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).