Subject: [PATCH] document how to reference previous commits

From: Heiko Voigt <[email-masked]>
Date: Thu, 28 Jul 2016 14:55:14 +0200

To reference previous commits people used to put just the abbreviated
SHA-1 into commit messages. This is what has evolved as a more
stable format for referencing commits. So lets document it for everyone
to lookup when needed.

Signed-off-by: Heiko Voigt <[email-masked]>
---
On Thu, Jul 28, 2016 at 01:16:36PM +0200, Heiko Voigt wrote:
> On Tue, Jul 26, 2016 at 10:22:07AM -0700, Stefan Beller wrote:
> > Usually we refer to the commit by a triple of "abbrev. sha1 (date, subject).
> > See d201a1ecd (2015-05-21, test_bitmap_walk: free bitmap with bitmap_free)
> > for an example. Or ce41720ca (2015-04-02, blame, log: format usage strings
> > similarly to those in documentation).
> > 
> > Apparently we put the subject first and then the date. I always did it
> > the other way
> > round, to there is no strict coding guide line, though it helps a lot to have an
> > understanding for a) how long are we in the "broken" state already as well as
> > b) what was the rationale for introducing it.
> 
> Ah ok did not know about this format. Will change that. I also will
> follow-up with a patch to document this in SubmittingPatches so we can
> point others to that...

Here we go. Made this a seperate patch, since it is not really connected
to the submodule-config-fix series.

Cheers Heiko

 Documentation/SubmittingPatches | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e8ad978..500230c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -121,6 +121,11 @@ its behaviour.  Try to make sure your explanation can be understood
 without external resources. Instead of giving a URL to a mailing list
 archive, summarize the relevant points of the discussion.
 
+If you want to reference a previous commit in the history of a stable
+branch use the format "abbreviated sha1 (subject, date)". So for example
+like this: "Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
+noticed [...]".
+
 
 (3) Generate your patch using Git tools out of your commits.
 
-- 
2.0.2.832.g083c931