From patchwork Mon Aug 16 12:58:33 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nicolas George X-Patchwork-Id: 29568 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6602:2a4a:0:0:0:0 with SMTP id k10csp2017234iov; Mon, 16 Aug 2021 05:58:48 -0700 (PDT) X-Google-Smtp-Source: ABdhPJzdVbCYC6fg/UaijVcexXVb228YTEOwPSOihRdy4BX0/8Tj1j8zMBvPtqH3sMRZKwr7SaPx X-Received: by 2002:a05:6402:1299:: with SMTP id w25mr20694961edv.30.1629118728602; Mon, 16 Aug 2021 05:58:48 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1629118728; cv=none; d=google.com; s=arc-20160816; b=tL3DpYLaBO1GLi6eaaY8QgGCzrZeNUhQw7wnXywc/DvN6JVT6w7SBzTX/+fK4sCW5V 68o2D9Fl2zRSTEtvemZZFwXelGKTsrzjPA6f6+awC7gxm9LlbmlZwxUW2pQEc3DLiKeL giW2IGxe3ZGZBZSLcc1mGMkq5MpYD5tWNtLkRqJ/EMcAg7jzd13ycr/Z1eEkAMj0iVyU F4DIJJ0CthBO41phSuWDp7gWn5MqD2nY94eezGVqV9hPrO63lZ0VPZQzzgkmE/1zSPa6 POvVirf+MjsIvKl2+14wNdtypf0VV/inyKuylUA+luP/BXJDTXqZ30OP4NJB3YfiPkR7 K0Hw== 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=uY0meCwYYuhu0D7yLrzytes1JQMfrZNQyUnlOQs3yIY=; b=elC8pyzAr/4z11NAgAA1TyyTLZpVJgd+xS9q4/kixzDoJKFA78hJw4zCsVg4GlpPhd rHeiLkYXTfysT0zM65PievrncFIgF2RmCHIdkDChwDa/V0biwaga3MBtgS3TOXOMhsoI +JtENtGn7kOSmMndJ/MvJbPLxDl2qoYbKMgPeoeJF1rfO4KWtVn72ANqmuYP39Byz1r8 MzY+a6gymJGnDSuRBaqbfBLeBfwm1QxiElatCsdZxuXLl027xt64PiO751AMKrF1cN9R gUA4D9fFM+4fX3Pw6jKgHu5RmjRibQpybK6F7HvVZkSPMqmJDdjvxQvR5tpqdv863Zlw K4xw== 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 j5si10063820ejj.184.2021.08.16.05.58.45; Mon, 16 Aug 2021 05:58:48 -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 260EF68A302; Mon, 16 Aug 2021 15:58:43 +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 C9258680610 for ; Mon, 16 Aug 2021 15:58:36 +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 17GCwaO6014604 for ; Mon, 16 Aug 2021 14:58:36 +0200 Received: by phare.normalesup.org (Postfix, from userid 1001) id 0EDB2EB5BC; Mon, 16 Aug 2021 14:58:36 +0200 (CEST) From: Nicolas George To: ffmpeg-devel@ffmpeg.org Date: Mon, 16 Aug 2021 14:58:33 +0200 Message-Id: <20210816125834.20867-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]); Mon, 16 Aug 2021 14:58:36 +0200 (CEST) Subject: [FFmpeg-devel] [PATCH v2] 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: 60INOQyBtv8I 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 | 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