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

[Gyan Doshi]

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 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).

"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:
> +
> + 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,

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