[FFmpeg-devel] [PATCH 6/6] doc/developer: deduplicate commit message rules

[Stefano Sabatini]

Il sab 26 ago 2023, 20:08 Anton Khirnov <anton at khirnov.net> ha scritto:

> The patches/committing section currently contains several
> partially-overlapping rules on commit messages. Merge and simplify them
> into one item.
> ---
>  doc/developer.texi | 41 ++++++++++++++++++-----------------------
>  1 file changed, 18 insertions(+), 23 deletions(-)
>
> diff --git a/doc/developer.texi b/doc/developer.texi
> index e4ba263581..fa417fc019 100644
> --- a/doc/developer.texi
> +++ b/doc/developer.texi
> @@ -340,13 +340,24 @@ missing samples or an implementation with a small
> subset of features.
>  Always check the mailing list for any reviewers with issues and test
>  FATE before you push.
>
> - at subheading Keep the main commit message short with an extended
> description below.
> -The commit message should have a short first line in the form of
> -a @samp{topic: short description} as a header, separated by a newline
> -from the body consisting of an explanation of why the change is necessary.
> -If the commit fixes a known bug on the bug tracker, the commit message
> -should include its bug ID. Referring to the issue on the bug tracker does
> -not exempt you from writing an excerpt of the bug in the commit message.
> + at subheading Commit messages
> +Commit messages are highly important tools for informing other developers
> on
> +what a given change does and why. Every commit must always have a properly
> +filled out commit message with the following format:
> + at example
> +area changed: Short 1 line description


Short => short given that we do not Capitalize

+
> +details describing what and why and giving references.
> + at end example
> +
> +If the commit addresses a known bug on our bug tracker or other external
> issue
> +(e.g. CVE), the commit message should include the relevant bug ID(s) or
> other
> +external identifiers. Note that this should be done in addition to a
> proper
> +explanation and not instead of it. Comments such as "fixed!" or "Changed
> it."
> +are not acceptable.
> +
> +When applying patches that have been discussed at length on the mailing
> list,
> +reference the thread in the commit message.
>
>  @subheading Testing must be adequate but not excessive.
>  If it works for you, others, and passes FATE then it should be OK to
> commit
> @@ -379,28 +390,12 @@ NOTE: If you had to put if()@{ .. @} over a large (>
> 5 lines) chunk of code,
>  then either do NOT change the indentation of the inner part within (do not
>  move it to the right)! or do so in a separate commit
>
> - at subheading Commit messages should always be filled out properly.
> -Always fill out the commit log message. Describe in a few lines what you
> -changed and why. You can refer to mailing list postings if you fix a
> -particular bug. Comments such as "fixed!" or "Changed it." are
> unacceptable.
> -Recommended format:
> -
> - at example
> -area changed: Short 1 line description
> -
> -details describing what and why and giving references.
> - at end example
> -
>  @subheading Credit the author of the patch.
>  Make sure the author of the commit is set correctly. (see git commit
> --author)
>  If you apply a patch, send an
>  answer to ffmpeg-devel (or wherever you got the patch from) saying that
>  you applied the patch.
>
> - at subheading Complex patches should refer to discussion surrounding them.
> -When applying patches that have been discussed (at length) on the mailing
> -list, reference the thread in the log message.
> -
>  @subheading Always wait long enough before pushing changes
>  Do NOT commit to code actively maintained by others without permission.
>  Send a patch to ffmpeg-devel. If no one answers within a reasonable
>

Lgtm otherwise, thanks.

>