Ksummit-Discuss Archive on lore.kernel.org
 help / color / Atom feed
From: Christian Brauner <christian@brauner.io>
To: Thomas Gleixner <tglx@linutronix.de>
Cc: ksummit-discuss@lists.linuxfoundation.org
Subject: Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Patch version changes in commit logs?
Date: Sat, 29 Jun 2019 11:10:39 +0200
Message-ID: <20190629091037.ysc6yhamypxq522b@brauner.io> (raw)
In-Reply-To: <alpine.DEB.2.21.1906290802360.1802@nanos.tec.linutronix.de>

On Sat, Jun 29, 2019 at 08:19:55AM +0200, Thomas Gleixner wrote:
> On Fri, 28 Jun 2019, Luck, Tony wrote:
> > On Fri, Jun 28, 2019 at 02:11:28PM -0600, Shuah Khan wrote:
> > > In a recent patch discussion, I learned that some maintainers would like
> > > to see patch version changes in the commit log.
> > > 
> > > I went looking in the git log and found a handful of recent commits with
> > > "Changes since" type information in the commit logs. It appears to be
> > > maintainer preference and a recent trend.
> > > 
> > > I see the value in including the information. It can be informative
> > > and valuable for future work in the area.
> > > 
> > > Is this something that we would like to see in all commits going forward? If
> > > so, updating submitting patch documentation and making
> > > sure the version information evolves from "informal" to more formal
> > > nature that fits in with the commit logs would be helpful.
> > > 
> > > Making sure it doesn't get out of hand and commit logs don't
> > > become too long to be useful would also be helpful.
> > > 
> > > Late entry, as I happened to come across this a day or two ago.
> > 
> > Sounds somewhat pointless. Picking on a recent commit I see:
> > 
> >     Changes since:
> >     v2:
> >      - Added Fixes tag to patch 1
> >      - Fixed typo
> >      - added GSWIP_TABLE_MAC_BRIDGE_STATIC and made use of it
> >      - used GSWIP_TABLE_MAC_BRIDGE in more places
> >     
> >     v1:
> >      - fix typo signle -> single
> > 
> > I don't see why someone in the future trying to debug some problem
> > introduced by this commit would care that earlier versions had some
> > spelling mistakes or were missing a Fixes: tag. :-)
> 
> Right.
> 
> > Where substantial changes were made between patch versions it
> > would be useful if the commit logs were adapted to say things like:
> > 
> >  "We considered using technique X to do this but rejected
> >   it because person Y said it had problem Z"
> > 
> > That captures for posterity the useful information without
> > bulking up the commit log with the blow-by-blow deltas of
> > how the patch series evolved across 27 versions submitted
> > to the mailing list.
> 
> What's really useful is when the commit has a Link tag:
> 
>        https://lore.kernel.org/lkml/$MESSAGE-ID
> 
> and if the submitters provide the same kind of link in their V(N)
> submission pointing to the V(N-1) in the cover letter:
> 
>        https://lore.kernel.org/lkml/$MESSAGE-ID-V(N-1)
> 
> If it's a single patch the link can be in the patch itself after the ---
> separator. That allows a quick lookup of the history.
> 
> I also really want the change history to be at that place. i.e.
> 
>  Subject ....
> 
>  changelog text
> 
>  Tags...
>  Signed-off-by: Joe Hacker
> 
>  ---
> 
>  V3: Fixed typo
> 
>  V2: Made it work
>      https://lore.kernel.org/.... (if single patch)
> 
>  ---
> 
>  diffstat
> 
>  ---
> 
>  patch
> 
> That way tools just strip the changes section away and the maintainer does
> not have to handle it manually.
> 
> Can we pretty please agree on that format and make it mandatory?

That sounds really useful. Imho, the ideal is:
- patch submissions:
  - Thomas format outlined above
- commit message in Linus/Maintainers tree:
  - lore-Link to the last sent submission that turned into the accepted
    patch (again, Thomas)
  - but keeping specific version information v1, ..., vn out of the
    commit message

I do like lore-Links a lot and I have made quite heavy use of them in
commit messages by using the format:

"We did x because of y. For the full rationale see [1]."

and then add the end of the commit message right before the DCOs I have
a "References" section:

/* References */
[1]: [6]: https://lore.kernel.org/lkml/<ID>

If we could codify this somewhere in the kernel documentation I'm all for it!

Christian

  reply index

Thread overview: 106+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-06-28 20:11 Shuah Khan
2019-06-28 20:51 ` Luck, Tony
2019-06-28 21:05   ` Kees Cook
2019-06-28 21:07   ` Shuah Khan
2019-06-28 21:13     ` James Bottomley
2019-06-28 21:42       ` Shuah Khan
2019-06-28 21:07   ` Wolfram Sang
2019-06-29  6:19   ` Thomas Gleixner
2019-06-29  9:10     ` Christian Brauner [this message]
2019-06-29 13:43     ` Andrea Parri
2019-06-29 15:16       ` Thomas Gleixner
2019-06-30 16:31         ` Konstantin Ryabitsev
2019-07-01  7:20           ` Peter Zijlstra
2019-07-01  7:49             ` Thomas Gleixner
2019-07-01  7:53               ` Takashi Iwai
2019-07-17  9:23                 ` Dan Carpenter
2019-07-17  9:27                   ` Dan Carpenter
2019-07-17  9:28                   ` Greg KH
2019-07-17 16:09                     ` Linus Walleij
2019-07-17 20:44                       ` Greg KH
2019-07-18  9:09                       ` Linus Walleij
2019-07-22 17:02                       ` Kees Cook
2019-07-22 17:12                         ` Joe Perches
2019-07-01 17:27               ` Steven Rostedt
2019-07-01 17:55                 ` Thomas Gleixner
2019-07-01  9:48           ` Andrea Parri
2019-07-01  9:51             ` Andrea Parri
2019-07-02  4:40     ` Leon Romanovsky
2019-07-02  7:27       ` Geert Uytterhoeven
2019-07-02  9:48         ` Leon Romanovsky
2019-06-29  6:57   ` Takashi Iwai
2019-06-29  7:09     ` Thomas Gleixner
2019-06-29  7:18       ` Takashi Iwai
2019-06-29 11:20         ` Mark Brown
2019-06-30 16:01           ` Mauro Carvalho Chehab
2019-07-01  1:35             ` Andrew Donnellan
2019-07-01 11:10               ` Mark Brown
2019-08-08  5:24               ` Andrew Donnellan
2019-07-01  9:05       ` Jiri Kosina
2019-07-01  9:15         ` Sergey Senozhatsky
2019-07-04 12:15       ` Michael Ellerman
2019-07-04 13:24         ` Geert Uytterhoeven
2019-07-04 14:16           ` Thomas Gleixner
2019-07-05  3:37             ` Michael Ellerman
2019-07-05  4:10               ` Michael Ellerman
2019-07-05  6:28                 ` Thomas Gleixner
2019-07-05  8:24                   ` Geert Uytterhoeven
2019-07-04 14:22         ` James Bottomley
2019-07-05  3:24           ` Michael Ellerman
2019-07-06 14:02             ` Alexandre Belloni
2019-07-06 14:57               ` James Bottomley
2019-07-05  3:40           ` Michael Ellerman
2019-07-05  8:40           ` Geert Uytterhoeven
2019-06-28 21:07 ` James Bottomley
2019-07-01 15:06 ` David Howells
2019-07-01 15:40   ` Thomas Gleixner
2019-07-01 15:48     ` Laurent Pinchart
2019-07-01 15:50     ` James Bottomley
2019-07-01 17:54       ` Thomas Gleixner
2019-07-02 14:20         ` James Bottomley
2019-07-02 14:49           ` Thomas Gleixner
2019-07-02 15:10             ` James Bottomley
2019-07-02 15:18               ` James Bottomley
2019-07-02 15:39                 ` Shuah Khan
2019-07-02 15:51                   ` James Bottomley
2019-07-02 16:30                     ` Kees Cook
2019-07-02 21:16                       ` Konstantin Ryabitsev
2019-07-02 21:33                       ` James Bottomley
2019-07-02 22:07                         ` Thomas Gleixner
2019-07-02 22:26                           ` James Bottomley
2019-07-02 22:43                             ` Theodore Ts'o
2019-07-02 22:49                               ` Thomas Gleixner
2019-07-03 23:52                                 ` Ralf Ramsauer
2019-07-02 22:53                               ` James Bottomley
2019-07-02 23:12                                 ` Thomas Gleixner
2019-07-02 23:04                               ` Kees Cook
2019-07-02 23:18                                 ` Theodore Ts'o
2019-07-02 23:31                                   ` Kees Cook
2019-07-02 23:33                                   ` James Bottomley
2019-07-03  4:16                                     ` Theodore Ts'o
2019-07-03  4:50                                       ` James Bottomley
2019-07-03 14:42                                         ` Kees Cook
2019-07-02 23:41                                   ` Kees Cook
2019-07-03  7:51                                     ` Greg KH
2019-07-03  8:56                               ` Laurent Pinchart
2019-07-03  9:12                                 ` Thomas Gleixner
2019-07-03 12:39                                   ` Leon Romanovsky
2019-07-03 22:53                                     ` Laurent Pinchart
2019-07-03 13:50                                 ` Theodore Ts'o
2019-07-03 14:10                                   ` Jan Kara
2019-07-03 17:05                                     ` Mark Brown
2019-07-03 19:11                                   ` Frank Rowand
2019-07-05  9:26                                   ` Linus Walleij
2019-07-05 19:34                                     ` Mike Rapoport
2019-07-06  4:42                                     ` Theodore Ts'o
2019-07-07 21:56                                       ` Frank Rowand
2019-07-03 23:03                                 ` James Bottomley
2019-07-04  7:10                                   ` Geert Uytterhoeven
2019-07-05  9:03                                 ` Linus Walleij
2019-07-02 22:48                             ` Thomas Gleixner
2019-07-02 23:05                               ` James Bottomley
2019-07-02 19:03                     ` Shuah Khan
2019-07-02 15:30               ` Thomas Gleixner
2019-07-02 15:40                 ` James Bottomley
2019-07-02 15:49                   ` Thomas Gleixner
2019-07-02 20:44               ` Jiri Kosina

Reply instructions:

You may reply publically 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=20190629091037.ysc6yhamypxq522b@brauner.io \
    --to=christian@brauner.io \
    --cc=ksummit-discuss@lists.linuxfoundation.org \
    --cc=tglx@linutronix.de \
    /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

Ksummit-Discuss Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/ksummit-discuss/0 ksummit-discuss/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 ksummit-discuss ksummit-discuss/ https://lore.kernel.org/ksummit-discuss \
		ksummit-discuss@lists.linuxfoundation.org
	public-inbox-index ksummit-discuss

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.linuxfoundation.lists.ksummit-discuss


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git