diff mbox series

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

Message ID 20210815091219.14301-1-george@nsup.org
State New
Headers show
Series [FFmpeg-devel] doc/git-howto: be more strict about commit message formatting. | expand


Context Check Description
andriy/x86_make success Make finished
andriy/x86_make_fate success Make fate finished
andriy/PPC64_make success Make finished
andriy/PPC64_make_fate success Make fate finished

Commit Message

Nicolas George Aug. 15, 2021, 9:12 a.m. UTC
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@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
diff mbox series


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,
+@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
+Example of a good commit message:
+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.
+@end example
+ptr might be NULL
+@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
+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