[FFmpeg-devel] [PATCH] doc/git-howto: be more strict about commit message formatting.

[Nicolas George]

Explain the format of the first line: "context: summary".
Add examples and explain bad practices.
Make it a section, so that we can link to it.

Signed-off-by: Nicolas George <george at nsup.org>
---
 doc/git-howto.texi | 38 ++++++++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)


James, ok that I used a commit of yours as an example of good commit
message? Otherwise, I can use the commit message for this very commit
instead.


diff --git a/doc/git-howto.texi b/doc/git-howto.texi
index 2b4fb80233..5c8ab90924 100644
--- a/doc/git-howto.texi
+++ b/doc/git-howto.texi
@@ -217,16 +217,46 @@ git config --global core.editor
 or set by one of the following environment variables:
 @var{GIT_EDITOR}, @var{VISUAL} or @var{EDITOR}.
 
-Log messages should be concise but descriptive. Explain why you made a change,
+ at section Writing a commit message
+
+Log messages should be concise but descriptive.
+
+The first line must contain the context, a colon and a very short
+summary of what the commit does. Then an empty line to separate, then if
+necessary a body with details, wrapped to 60-72 characters lines (except
+code).
+
+Example of a good commit message:
+
+ at example
+avcodec/cbs: add a helper to read extradata within packet side data
+
+Using ff_cbs_read() on the raw buffer will not parse it as extradata,
+resulting in parsing errors for example when handling ISOBMFF avcC.
+This helper works around that.
+ at end example
+
+ at example
+ptr might be NULL
+ at end example
+
+In the body of the message, explain why you made a change,
 what you did will be obvious from the changes themselves most of the time.
 Saying just "bug fix" or "10l" is bad. Remember that people of varying skill
 levels look at and educate themselves while reading through your code. Don't
-include filenames in log messages, Git provides that information.
+include filenames in log messages except in the context, Git provides that
+information.
+
+If the commit fixes a registered issue, state it in a separate line of the
+body: @code{Fix Trac ticket #42.}
 
-Possibly make the commit message have a terse, descriptive first line, an
-empty line and then a full description. The first line will be used to name
+The first line will be used to name
 the patch by @command{git format-patch}.
 
+Common mistakes for the first line, as seen in @command{git log --oneline}
+include: missing context at the beginning; description of what the code did
+before the patch; line too long or wrapped to the second line.
+
 @section Preparing a patchset
 
 @example
-- 
2.30.2