From patchwork Sun Jul 12 21:53:00 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Manolis Stamatogiannakis X-Patchwork-Id: 20983 Delivered-To: andriy.gelman@gmail.com Received: by 2002:a25:80ca:0:0:0:0:0 with SMTP id c10csp2182974ybm; Sun, 12 Jul 2020 14:53:46 -0700 (PDT) X-Google-Smtp-Source: ABdhPJyOPFAufPZZdR3tb9QB7yL2TX0JhQIomR9e5Tm75Vf9oeW7caNYy540qQwmktW5hNCGVykk X-Received: by 2002:a1c:ed0b:: with SMTP id l11mr15859287wmh.121.1594590826117; Sun, 12 Jul 2020 14:53:46 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1594590826; cv=none; d=google.com; s=arc-20160816; b=PUgnSxgFtUtiZzjgr+dxc5rgF2XXr2trjAKIPIjeuGcMxsLS/nTjK3GJqA4D5zz8RT y6MvLhrdQvcZfiUm1lFmSwPHvOqckiLVdMRJOMqeay6gHoNv3WLCViInungelA1L76lY QVdL7GV19R2r+wpng8+BOn30HXYz5PY+x89BjO4j4DuoIMpZ1YGyrdD7DXlewK5hs/dm JQ5pRsQ0iJSZLKsHVGsjhZaJ2d5zgzy0ocd0y75Q/RQj1RayREcPgS8gSrA6wXXEFDyQ HkUgwg1gUXIqVq2j1rVjTKsBv2o6Fb5UPO+9Q999jwJEl/qOS6MXTGoySYd4szlCDWlN G+Ew== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:mime-version:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:references:in-reply-to:message-id:date :to:from:dkim-signature:delivered-to; bh=qRtQEsFESXYnbevwi1uyidPKukagFoZ8g1kryxtTMlU=; b=NoW2uwtnuKutjJTQxqEln5duv2y7ZDN4GBwwqtRWabcSHbMm4peSXxzxynzOf1ShDE 1Q4Py/BHsfzxK1buPoPocSBPvUiKFHEi+0ba3solPgWXla+3ScMO7rzYkWTsV2V1tcKy IhWOolVGPWHqyUh0JSnsEqk3qIKI1QmYsCpoC1TKMl1ZkIKox/DJgOT/2V5nh5zvNd+E T78glw2SJwBrLzJFC2liYRXuEAPwS8TAx5Anzk74w7et+6t3HjiMU0f8vapAMhLXjqg0 ARgKt2hs2E8WO9kaF/QtJAgUpMObAzP7clM7ESO+lASoK53ZZLFgYbS15v5kVQKYOPxd tcMA== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20161025 header.b=uFLQUqMQ; 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; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id p12si10284034wmc.170.2020.07.12.14.53.44; Sun, 12 Jul 2020 14:53:46 -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; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20161025 header.b=uFLQUqMQ; 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; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 85D0A68A383; Mon, 13 Jul 2020 00:53:39 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-ed1-f52.google.com (mail-ed1-f52.google.com [209.85.208.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id D3B3B68A383 for ; Mon, 13 Jul 2020 00:53:32 +0300 (EEST) Received: by mail-ed1-f52.google.com with SMTP id d16so10160809edz.12 for ; Sun, 12 Jul 2020 14:53:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=K6Na3M//Qog/lvHChfp/bXrh1aLPbjjI5i2CVIQ3VwQ=; b=uFLQUqMQJPhrZaMBQ00RTv/Yer+Gq9JYoEQR2rEEHdOMp4EEV6UDP+6/4jh8xhsIup U28FB0T0DxZLRAhIReFHXaPlDRFOG/7FGsEjYHnuing0XQnywepane9VRSdzuAyXNU31 ojQQE8UCTEhRLGN3keVkrkpfDSNInnQJq070h3Q5oKGTsq3b/rFnKdfYQysUfvo/Hh2N 3ZlZ3dBc+AFOkPjtA/+PUS1YjT6dqquHvX5Tne1jgnSuLka8wTdMfR9lhfwuZHJc2lyj b0JEjtpj/As9tiO+mlQcwI0egWqq7fxREy/MKF6XD27n4vA2hHXmubfSIGknxs5XSMOT ynWQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=K6Na3M//Qog/lvHChfp/bXrh1aLPbjjI5i2CVIQ3VwQ=; b=JGbKPeiJknTZ5bq3+5rS9IapNr8YIkSHtcv1DG/vPAfRHJfnnYx0RBuMjkC8IrhDHR csUW3QXQpnOE9FAARoS13PHIPr0+GjnPhl3WmV555jh0Xm7LxcZxsqQIrUlY2fQ3ISRR wImvSxdBHWAiIVvTjtLief+snJbUO3Ts6ONDvVWQhc1czfdHGAZ/KK7WPu/YZjls/0XS Po3sc6ImM0QWoZCDn1E24mkxHL4nAweeU3Yh/JGv05ThJOIwId2Q/8vrAR2Oqp9RPJk2 xhl/PJP0QyrytdU/MIzPs/Mj1JSW4vUhJH9Eah9bYlu+Da0PzmwYsgXApJVXyJjfCFeq M0vQ== X-Gm-Message-State: AOAM532AYFpO0eHUeZyXMsSqQ25b1Kam+OY3J3LCPzT89oaFACf2MKMv 3QZuJB22PCnbY9bgp7k1B4h+WJEFhYCR0A== X-Received: by 2002:a05:6402:180a:: with SMTP id g10mr77531468edy.152.1594590811763; Sun, 12 Jul 2020 14:53:31 -0700 (PDT) Received: from wasteland.vu.local ([145.108.189.179]) by smtp.gmail.com with ESMTPSA id p4sm8464076eji.123.2020.07.12.14.53.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 12 Jul 2020 14:53:31 -0700 (PDT) From: Manolis Stamatogiannakis To: ffmpeg-devel@ffmpeg.org Date: Sun, 12 Jul 2020 23:53:00 +0200 Message-Id: <20200712215301.24889-2-mstamat@gmail.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200712215301.24889-1-mstamat@gmail.com> References: <20200712215301.24889-1-mstamat@gmail.com> Subject: [FFmpeg-devel] [PATCH v2 2/3] doc/developer.texi: Restructured Submitting patches section. X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.20 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 Cc: Manolis Stamatogiannakis MIME-Version: 1.0 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: Pj5eBGvmitJ6 Content-Length: 6627 - Main text split to two sections. - Detailed checklist for new codecs or formats demoted to section. - Detailed checklist for patch submission demoted to section. Signed-off-by: Manolis Stamatogiannakis --- doc/developer.texi | 64 +++++++++++++++++++++++++++++++--------------- 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/doc/developer.texi b/doc/developer.texi index 585c37d241..c47d23e349 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -457,31 +457,49 @@ Finally, keep in mind the immortal words of Bill and Ted, @anchor{Submitting patches} @chapter Submitting patches -First, read the @ref{Coding Rules} above if you did not yet, in particular +@anchor{patch guidelines} +@section Guidelines for preparing a patch + +The @strong{absolute minimum} you have to do before submitting a patch are the +following: + +@enumerate +@item Carefully read the @ref{Coding Rules} above if you did not yet, in particular the rules regarding patch submission. -When you submit your patch, please use @code{git format-patch} or -@code{git send-email}. We cannot read other diffs :-). +@item Make sure your commit messages accurately describe the changes made +(e.g. 'replaces lrint by lrintf') and why these changes are made (e.g. +'*BSD isn't C99 compliant and has no lrint()'). -Also please do not submit a patch which contains several unrelated changes. -Split it into separate, self-contained pieces. This does not mean splitting -file by file. Instead, make the patch as small as possible while still -keeping it as a logical unit that contains an individual change, even -if it spans multiple files. This makes reviewing your patches much easier -for us and greatly increases your chances of getting your patch applied. +@item Make sure you use @code{git format-patch} or @code{git send-email} to prepare +your patch. We cannot read other diffs :-). + +@item Run the @ref{Regression tests, regression tests} before submitting a patch +in order to verify it does not cause unexpected problems. -Use the patcheck tool of FFmpeg to check your patch. -The tool is located in the tools directory. +@item If you send your patches with an external email client +(i.e. not @code{git send-email}), make sure to send each patch as a separate +email. Do not attach several patches to the same email! -Run the @ref{Regression tests} before submitting a patch in order to verify -it does not cause unexpected problems. +@item Do not submit a patch which contains several unrelated changes. +@end enumerate + +Additionally, it is also important that each patch is logically +self-contained. I.e. each patch should be as small as possible, +while still containing a meaningful individual change. +Patches spanning multiple files are perfectly fine, as long as they can +be seen as a single logical unit. -It also helps quite a bit if you tell us what the patch does (for example -'replaces lrint by lrintf'), and why (for example '*BSD isn't C99 compliant -and has no lrint()') +Following these guidelines makes reviewing your patches much easier +for us and greatly increases your chances of getting your patch applied. +To further reduce the chance that you will need to revise your patch, +it is also recommended to go through the detailed +@ref{patch submission checklist, patch} and +@ref{new codec format checklist, new codec or format} +checklists. -Also please if you send several patches, send each patch as a separate mail, -do not attach several unrelated patches to the same mail. +@anchor{patch submission process} +@section Patch submission and revision process Patches should be posted to the @uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel} @@ -517,7 +535,8 @@ its @emph{roll-counter}. This is achieved by adding a @code{-v } argument to @code{git format-patch}/@code{git send-email} commands. While this is not a strict requirement, it is a commonly followed good practice. -@chapter New codecs or formats checklist +@anchor{new codec format checklist} +@section New codecs or formats checklist @enumerate @item @@ -569,7 +588,8 @@ Did you make sure it compiles standalone, i.e. with @end enumerate -@chapter Patch submission checklist +@anchor{patch submission checklist} +@section Patch submission checklist @enumerate @item @@ -594,6 +614,10 @@ of @dfn{sign-off}. @item Did you provide a clear git commit log message? +@item +Did you use the @code{patcheck} tool of FFmpeg to check your patch +for common issues? E.g. @code{tools/patcheck *.patch}. + @item Is the patch against latest FFmpeg git master branch?