From patchwork Sun Aug 15 09:12:19 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nicolas George X-Patchwork-Id: 29521 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6602:2a4a:0:0:0:0 with SMTP id k10csp1082061iov; Sun, 15 Aug 2021 02:12:32 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwClof2/ZPDJ5hJlno2cogVlQ6cgusXmFO99C/PiMdQ9psDLo4uDdYYFnEikrcEVtx+W8LG X-Received: by 2002:aa7:da4a:: with SMTP id w10mr13400038eds.206.1629018752508; Sun, 15 Aug 2021 02:12:32 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1629018752; cv=none; d=google.com; s=arc-20160816; b=VJLHw8JrrLk/3m0+CquWbg5sX4cTfXGcScSUObpFqsf4Mj5l2anadvQh9ul4ptEfm7 t/qhtc7PdC+qbVQlg2XyJTZnfhtK2IiKYfZByqMVDiQrG69celZIX1+LD6PMR+eelm2c PfpgLEGdGWekgCWfw8bQNn11m3RWGzYo1adEqk7Lvskfmmc+guwop6wmYfThNZjOKBJ9 eOpEHGbU2YuhrPdEhbUH7Eoq+Bn68bmj/51hYoRpZ2jYSOUcSDtiBh6zePlJDflq8Exf 9BJTb34TS5qbE+Im3M7TOExVpriKGotwUO+GpDVq1PjNchaRCLpGFKvzRVQqFImy1u5C fFUQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:message-id:date:to:from :delivered-to; bh=FWFQ544rlYObXjTk4AXMKSUI5YozxbKsMtkFQPXinTo=; b=FCsuDfeZewS68ATb60SSBowAXOL/MNcDFoOXUCLLv7G1wLEZkhfoqZVZV8x0paqAU0 U6Pj1L3MYCB99N35z8YwMCYfDrc6lXPFohdvnNMw4LXoNDGmPniJbfqoy5ns9sfRn5/c 7/bqyG21sKKu3LjB4nguufZ6dJCpX2xryERvT95oR1GFaM2J5c+XfwSgsM76GE87GkHW TnU2W5ybtsMP/ebUBmIL9cXanpfp/8hZNIuFUhwJMdl8p+SCHT1yK2OdgQ3kkh7vFQnZ cb0bwvdyXATkcu2T18dczPrrr3vpnVW58gW8KcuigL1SkTFC+WsKvZBZVpyXOUbioAgf 34mw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id h15si7054954ejj.98.2021.08.15.02.12.32; Sun, 15 Aug 2021 02:12:32 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 9E7CB68A12D; Sun, 15 Aug 2021 12:12:29 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from nef.ens.fr (nef2.ens.fr [129.199.96.40]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 2CC6868981E for ; Sun, 15 Aug 2021 12:12:23 +0300 (EEST) X-ENS-nef-client: 129.199.129.80 ( name = phare.normalesup.org ) Received: from phare.normalesup.org (phare.normalesup.org [129.199.129.80]) by nef.ens.fr (8.14.4/1.01.28121999) with ESMTP id 17F9CMBk025295 for ; Sun, 15 Aug 2021 11:12:22 +0200 Received: by phare.normalesup.org (Postfix, from userid 1001) id 632F6EB5BC; Sun, 15 Aug 2021 11:12:22 +0200 (CEST) From: Nicolas George To: ffmpeg-devel@ffmpeg.org Date: Sun, 15 Aug 2021 11:12:19 +0200 Message-Id: <20210815091219.14301-1-george@nsup.org> X-Mailer: git-send-email 2.30.2 MIME-Version: 1.0 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (nef.ens.fr [129.199.96.32]); Sun, 15 Aug 2021 11:12:22 +0200 (CEST) Subject: [FFmpeg-devel] [PATCH] doc/git-howto: be more strict about commit message formatting. X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: 6JIG+IbRgCMQ 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 --- 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 instead. 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 +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 + +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 +information. + +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 @example