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 <geo...@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
+@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:
+
+@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.
+@end example
+
+@example
+ptr might be NULL
+@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
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
