[FFmpeg-devel] [PATCH v2] 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 | 46 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 8 deletions(-)


Added "If the summary on the first line is not enohgh" in the paragraph
about the body.

Will push soon if nobody comments.


diff --git a/doc/git-howto.texi b/doc/git-howto.texi
index 2b4fb80233..f176e18c15 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,
-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.
-
-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
+ 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
+
+If the summary on the first line is not enohgh, 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 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.}
+
+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