| Message ID | 20210816125834.20867-1-george@nsup.org |
|---|---|
| State | New |
| Headers | show |
| Series | [FFmpeg-devel,v2] 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 |
On 2021-08-16 06:28 pm, Nicolas George wrote: > 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 | 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). "Details can be added, when necessary, separated by an empty line. These lines should not exceed 72 characters, except when containing 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, enohgh --> enough Isn't the first line just the log message referred to above? If so, this and the next line and a half seem repetitive. > +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 Seems OK. Don't mind if I rephrase, later on. Regards, Gyan
Gyan Doshi (12021-08-16): > "Details can be added, when necessary, separated by an empty line. These > lines should not exceed 72 characters, except when containing code." Thanks, it is better. I have slightly amended it to: The first line must contain the context, a colon and a very short summary of what the commit does. Details can be added, if necessary, separated by an empty line. These details should not exceed 60-72 characters per line, except when containing code. > enohgh --> enough Fixed, thanks. > Isn't the first line just the log message referred to above? If so, this and > the next line and a half seem repetitive. No, "log" is just an obsolete wording inherited from the SVN habits, AFAIU, "log message" and "commit message" are the same thing and cover the whole message. I have called the first line the summary. I see some people call it the subject. > Seems OK. Don't mind if I rephrase, later on. I will leave some more time then. Regards,
On 2021-08-16 06:50 pm, Nicolas George wrote: > Gyan Doshi (12021-08-16): >> "Details can be added, when necessary, separated by an empty line. These >> lines should not exceed 72 characters, except when containing code." > Thanks, it is better. I have slightly amended it to: > > The first line must contain the context, a colon and a very short > summary of what the commit does. Details can be added, if necessary, > separated by an empty line. These details should not exceed 60-72 characters The maximum, if specified, should be a single value. > per line, except when containing code. > >> enohgh --> enough > Fixed, thanks. > >> Isn't the first line just the log message referred to above? If so, this and >> the next line and a half seem repetitive. > No, "log" is just an obsolete wording inherited from the SVN habits, > AFAIU, "log message" and "commit message" are the same thing and cover > the whole message. > > I have called the first line the summary. I see some people call it the > subject. > >> Seems OK. Don't mind if I rephrase, later on. > I will leave some more time then. Don't hold up on my account. I'll do it later when I survey that whole page for corrections and improvements. Regards, Gyan
Gyan Doshi (12021-08-16): > The maximum, if specified, should be a single value. Strictly speaking, yes. But I want to express that it is ok to choose a lower maximum on a per-commit basis. I personally wrap to 64-66. > Don't hold up on my account. I'll do it later when I survey that whole page > for corrections and improvements. Ok. Pushed. Thanks. Regards,
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
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 | 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.