From patchwork Sat Oct 1 19:19:16 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Josh Dekker X-Patchwork-Id: 815 Delivered-To: ffmpegpatchwork@gmail.com Received: by 10.103.140.66 with SMTP id o63csp854940vsd; Sat, 1 Oct 2016 12:19:34 -0700 (PDT) X-Received: by 10.195.3.4 with SMTP id bs4mr11420664wjd.193.1475349574301; Sat, 01 Oct 2016 12:19:34 -0700 (PDT) Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id 11si11210253wmn.108.2016.10.01.12.19.33; Sat, 01 Oct 2016 12:19:34 -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=@itanimul.li; dkim=neutral (body hash did not verify) header.i=@messagingengine.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 B7766680C25; Sat, 1 Oct 2016 22:19:17 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from out3-smtp.messagingengine.com (out3-smtp.messagingengine.com [66.111.4.27]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 0015E6805C3 for ; Sat, 1 Oct 2016 22:19:10 +0300 (EEST) Received: from compute7.internal (compute7.nyi.internal [10.202.2.47]) by mailout.nyi.internal (Postfix) with ESMTP id A4C1520E52 for ; Sat, 1 Oct 2016 15:19:23 -0400 (EDT) Received: from frontend1 ([10.202.2.160]) by compute7.internal (MEProxy); Sat, 01 Oct 2016 15:19:23 -0400 DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d=itanimul.li; h= date:from:in-reply-to:message-id:references:subject:to :x-sasl-enc:x-sasl-enc; s=mesmtp; bh=Aj/rG8LvQWRIpUuTYa/GWSNnzrQ =; b=qvpOodi/dnUMq7rHNInCCuWCmTa3f77hQ82GeprTgTllHfoJTqG6H42HcR9 tn2/qTKR/KGVcqsr7pO/v9VHnrZNnk7d+eTz90Ies8yDBqaitSPHHUZCiSWNF2lr zzA0kWP009sXaDGYn7gJe7ZnRnIHCHehch07pAAupoOn/7u0= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d= messagingengine.com; h=date:from:in-reply-to:message-id :references:subject:to:x-sasl-enc:x-sasl-enc; s=smtpout; bh=Aj/r G8LvQWRIpUuTYa/GWSNnzrQ=; b=ZFf/EpCqBBkyghnq/NHkRCsmDWRCuVhhH94t xakwSuK7XMBlF8FPTTtR4FvvGAUJMzm60eHPbfXnUi8gHIjr95BuDrSUlT9mNUxF TW4y4CMOWDkx+S52ohmrDZlw3t5dIZ0DygWlupI7NAo9dUlzubM4PNpzsI0QcqFh xEIUFmY= X-Sasl-enc: /9PORitgGLkWipK5ote/uvQnMtX286h3Z6Nm3FdIEdC9 1475349563 Received: from localhost (cpc75394-sotn16-2-0-cust168.15-1.cable.virginm.net [82.22.8.169]) by mail.messagingengine.com (Postfix) with ESMTPA id 0CA9AF2985 for ; Sat, 1 Oct 2016 15:19:22 -0400 (EDT) From: Josh de Kock To: ffmpeg-devel@ffmpeg.org Date: Sat, 1 Oct 2016 20:19:16 +0100 Message-Id: <20161001191916.12783-1-josh@itanimul.li> X-Mailer: git-send-email 2.8.4 (Apple Git-73) In-Reply-To: References: Subject: [FFmpeg-devel] [PATCH v2] doc/developer: improve development policy formatting 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 MIME-Version: 1.0 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" This commit also rewords some of the policies for more clarity. Signed-off-by: Josh de Kock --- doc/developer.texi | 172 +++++++++++++++++++++++++---------------------------- 1 file changed, 82 insertions(+), 90 deletions(-) diff --git a/doc/developer.texi b/doc/developer.texi index 4d3a7ae..b3f5218 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -246,8 +246,9 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}: @section Development Policy -@enumerate -@item +@subsection Patches/Committing + +@subheading Licenses for patches must be compatible with FFmpeg. Contributions should be licensed under the @uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1}, including an "or any later version" clause, or, if you prefer @@ -260,15 +261,13 @@ preferred. If you add a new file, give it a proper license header. Do not copy and paste it from a random place, use an existing file as template. -@item -You must not commit code which breaks FFmpeg! (Meaning unfinished but -enabled code which breaks compilation or compiles but does not work or -breaks the regression tests) -You can commit unfinished stuff (for testing etc), but it must be disabled -(#ifdef etc) by default so it does not interfere with other developers' -work. +@subheading You must not commit code which breaks FFmpeg! +This means unfinished code which is enabled and breaks compilation, +compiles but does not work or breaks the regression tests). Always +check the mailing list for any reviewers with issues and test FATE +before you push. -@item +@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. @@ -276,53 +275,7 @@ 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. -@item -You do not have to over-test things. If it works for you, and you think it -should work for others, then commit. If your code has problems -(portability, triggers compiler bugs, unusual environment etc) they will be -reported and eventually fixed. - -@item -Do not commit unrelated changes together, split them into self-contained -pieces. Also do not forget that if part B depends on part A, but A does not -depend on B, then A can and should be committed first and separate from B. -Keeping changes well split into self-contained parts makes reviewing and -understanding them on the commit log mailing list easier. This also helps -in case of debugging later on. -Also if you have doubts about splitting or not splitting, do not hesitate to -ask/discuss it on the developer mailing list. - -@item -Do not change behavior of the programs (renaming options etc) or public -API or ABI without first discussing it on the ffmpeg-devel mailing list. -Do not remove functionality from the code. Just improve! - -Note: Redundant code can be removed. - -@item -Do not commit changes to the build system (Makefiles, configure script) -which change behavior, defaults etc, without asking first. The same -applies to compiler warning fixes, trivial looking fixes and to code -maintained by other developers. We usually have a reason for doing things -the way we do. Send your changes as patches to the ffmpeg-devel mailing -list, and if the code maintainers say OK, you may commit. This does not -apply to files you wrote and/or maintain. - -@item -We refuse source indentation and other cosmetic changes if they are mixed -with functional changes, such commits will be rejected and removed. Every -developer has his own indentation style, you should not change it. Of course -if you (re)write something, you can use your own style, even though we would -prefer if the indentation throughout FFmpeg was consistent (Many projects -force a given indentation style - we do not.). If you really need to make -indentation changes (try to avoid this), separate them strictly from real -changes. - -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 - -@item +@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. @@ -334,57 +287,68 @@ area changed: Short 1 line description details describing what and why and giving references. @end example -@item +@subheading Do not commit unrelated changes together, +You should split them into self-contained pieces. Also do not forget that +if part B depends on part A, but A does not depend on B, then A can and should +be committed first and separate from B. Keeping changes well split into +self-contained parts makes reviewing and understanding them on the commit log +mailing list easier. This also helps in case of debugging later on. +Also if you have doubts about splitting or not splitting, do not hesitate to +ask/discuss it on the developer mailing list. + +@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. +If you apply a patch, send an answer to ffmpeg-devel (or wherever you got the +patch from) saying that you applied the patch. -@item +@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. -@item +@subheading Ask before you change the build system (configure, etc). +Do not commit changes to the build system (Makefiles, configure script) +which change behavior, defaults etc, without asking first. The same +applies to compiler warning fixes, trivial looking fixes and to code +maintained by other developers. We usually have a reason for doing things +the way we do. Send your changes as patches to the ffmpeg-devel mailing +list, and if the code maintainers say OK, you may commit. This does not +apply to files you wrote and/or maintain. + +@subheading Testing must be adequate but not is not required to be excessive. +If it works for you, others, and passes FATE then it should be OK to commit +it, provided it fits the other committing criteria. You should not worry about +over-testing things. If your code has problems (portability, triggers +compiler bugs, unusual environment etc) they will be reported and eventually +fixed. + +@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 instead. If no one answers within a reasonable -timeframe (12h for build failures and security fixes, 3 days small changes, +Send a patch to ffmpeg-devel. If no one answers within a reasonable +time-frame (12h for build failures and security fixes, 3 days small changes, 1 week for big patches) then commit your patch if you think it is OK. Also note, the maintainer can simply ask for more time to review! -@item -Subscribe to the ffmpeg-cvslog mailing list. The diffs of all commits -are sent there and reviewed by all the other developers. Bugs and possible -improvements or general questions regarding commits are discussed there. We -expect you to react if problems with your code are uncovered. - -@item -Update the documentation if you change behavior or add features. If you are -unsure how best to do this, send a patch to ffmpeg-devel, the documentation -maintainer(s) will review and commit your stuff. +@subsection Code -@item -Try to keep important discussions and requests (also) on the public -developer mailing list, so that all developers can benefit from them. +@subheading API/ABI breakages and changes should be discussed before they are made. +Do not change behavior of the programs (renaming options etc) or public +API or ABI without first discussing it on the ffmpeg-devel mailing list. +Do not remove widely used functionality or features (redundant code can be removed). -@item -Never write to unallocated memory, never write over the end of arrays, -always check values read from some untrusted source before using them -as array index or other risky things. +@subheading Remember to check if you need to bump versions for libav* +Depending on the change, you may need to change the version integer. -@item -Remember to check if you need to bump versions for the specific libav* -parts (libavutil, libavcodec, libavformat) you are changing. You need -to change the version integer. Incrementing the first component means no backward compatibility to previous versions (e.g. removal of a function from the public API). Incrementing the second component means backward compatible change (e.g. addition of a function to the public API or extension of an existing data structure). + Incrementing the third component means a noteworthy binary compatible change (e.g. encoder bug fix that matters for the decoder). The third component always starts at 100 to distinguish FFmpeg from Libav. -@item +@subheading Warnings for correct code may be disabled if there is no other option. Compiler warnings indicate potential bugs or code with bad style. If a type of warning always points to correct and clean code, that warning should be disabled, not the code changed. @@ -393,14 +357,42 @@ If it is a bug, the bug has to be fixed. If it is not, the code should be changed to not generate a warning unless that causes a slowdown or obfuscates the code. -@item +@subheading Cosmetic changes should be kept in separate patches. +We refuse source indentation and other cosmetic changes if they are mixed +with functional changes, such commits will be rejected and removed. Every +developer has his own indentation style, you should not change it. Of course +if you (re)write something, you can use your own style, even though we would +much prefer it if the indentation throughout FFmpeg were consistent. If you +really need to make indentation changes (try to avoid this), separate them +strictly from real changes. + +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 + +@subsection Documentation/Other + +@subheading Subscribe to the ffmpeg-cvslog mailing list. +The diffs of all commits are sent there and reviewed by all the other developers. +Bugs and possible improvements or general questions regarding commits are +discussed there. We expect you to react if problems with your code are uncovered. + +@subheading Keep the documentation up to date. +Update the documentation if you change behavior or add features. If you are +unsure how best to do this, send a patch to ffmpeg-devel, the documentation +maintainer(s) will review and commit your stuff. + +@subheading Important discussions should be accessible to all. +Try to keep important discussions and requests (also) on the public +developer mailing list, so that all developers can benefit from them. + +@subheading Check your entries in MAINTAINERS. Make sure that no parts of the codebase that you maintain are missing from the @file{MAINTAINERS} file. If something that you want to maintain is missing add it with your name after it. If at some point you no longer want to maintain some code, then please help in finding a new maintainer and also don't forget to update the @file{MAINTAINERS} file. -@end enumerate - +@* We think our rules are not too hard. If you have comments, contact us. @section Code of conduct