linux-kernel - Re: [patch 2/2] Documentation/process: Add tip tree handbook

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20181108073051.GC20032@gmail.com>
Date:   Thu, 8 Nov 2018 08:30:51 +0100
From:   Ingo Molnar <mingo@...nel.org>
To:     Thomas Gleixner <tglx@...utronix.de>
Cc:     LKML <linux-kernel@...r.kernel.org>, x86@...nel.org,
        Peter Zijlstra <peterz@...radead.org>,
        Paul McKenney <paulmck@...ux.vnet.ibm.com>,
        John Stultz <john.stultz@...aro.org>,
        Arnaldo Carvalho de Melo <acme@...hat.com>,
        Frederic Weisbecker <frederic@...nel.org>,
        Jonathan Corbet <corbet@....net>,
        Andy Lutomirski <luto@...nel.org>,
        Marc Zyngier <marc.zyngier@....com>,
        Daniel Lezcano <daniel.lezcano@...aro.org>,
        Dave Hansen <dave.hansen@...ux.intel.com>,
        Ard Biesheuvel <ard.biesheuvel@...aro.org>,
        Will Deacon <will.deacon@....com>,
        Mark Brown <broonie@...nel.org>,
        Dan Williams <dan.j.williams@...el.com>
Subject: Re: [patch 2/2] Documentation/process: Add tip tree handbook


* Thomas Gleixner <tglx@...utronix.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@...l>
> +
> +   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@...l>

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@...l>

... 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@...l>

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