LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Stefan Richter <stefanr@s5r6.in-berlin.de>
To: Paul Jackson <pj@sgi.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
	torvalds@linux-foundation.org, linux-kernel@vger.kernel.org,
	akpm@linux-foundation.org
Subject: Re: [PATCH] Documenting patch tags yet one more time
Date: Sat, 09 Feb 2008 09:37:05 +0100	[thread overview]
Message-ID: <47AD6631.8070800@s5r6.in-berlin.de> (raw)
In-Reply-To: <20080208182317.525c4d1f.pj@sgi.com>

Paul Jackson would like to:
> explain more clearly that PATCH's
> should start off, right from the top or after the initial From: line if
> present, with:
> 
>   - The body of the explanation, which will be copied to the
>     permanent changelog to describe this patch.
> 
> rather than opening with ephemeral reactions to the discussion of the
> moment which will make little "sense to a competent reader who has long
> since forgotten the immediate details of the discussion that might have
> led to this patch."
> 
> As best my legalistic mind understands the patch format, such ephemeral
> reactions should go after the "---" marker line, in the same section as
> the diffstat would be placed.
> 
> Or perhaps the patch format should be changed in this regard, since it
> is cumbersome and unnatural to embed the ephemeral opening comments
> half way down the patch, rather than opening with them.

In common practice, the changelog does not start before the _last_ From:
line (rather than the initial From: line).

	ephemera
	From: author
	changelog
	tags
	changelog, continued
	tags
	---
	ephemera, diffstat
	diff
	ephemera

There may be a Date: somewhere before the changelog as well.  The first
line of the changelog is the one to appear in shortlogs.  It may be
preceded by Subject:.
-- 
Stefan Richter
-=====-==--- --=- -=--=
http://arcgraph.de/sr/

  reply	other threads:[~2008-02-09  8:38 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2008-02-08 16:51 [PATCH] Documentation/patch-tags, " Jonathan Corbet
2008-02-08 17:07 ` Pekka Enberg
2008-02-08 18:00 ` Linus Torvalds
2008-02-08 19:01   ` Paul Jackson
2008-02-08 20:42     ` [PATCH] Documenting patch tags yet " Jonathan Corbet
2008-02-09  0:23       ` Paul Jackson
2008-02-09  8:37         ` Stefan Richter [this message]
2008-02-08 20:50   ` [PATCH] Documentation/patch-tags, " Junio C Hamano
2008-02-18  2:58   ` Neil Brown
2008-02-18  3:15     ` Paul Jackson
2008-02-18  3:58       ` Neil Brown

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=47AD6631.8070800@s5r6.in-berlin.de \
    --to=stefanr@s5r6.in-berlin.de \
    --cc=akpm@linux-foundation.org \
    --cc=corbet@lwn.net \
    --cc=linux-kernel@vger.kernel.org \
    --cc=pj@sgi.com \
    --cc=torvalds@linux-foundation.org \
    --subject='Re: [PATCH] Documenting patch tags yet one more time' \
    /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

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).