From patchwork Fri Nov 7 14:49:43 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 40416 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-ee0-f70.google.com (mail-ee0-f70.google.com [74.125.83.70]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id A8A54240F7 for ; Fri, 7 Nov 2014 14:50:11 +0000 (UTC) Received: by mail-ee0-f70.google.com with SMTP id b57sf3460491eek.9 for ; Fri, 07 Nov 2014 06:50:10 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:from:to:date:message-id :mime-version:subject:precedence:list-id:list-unsubscribe :list-archive:list-post:list-help:list-subscribe:errors-to:sender :x-original-sender:x-original-authentication-results:mailing-list :content-type:content-transfer-encoding; bh=G3M1aSrkLSNeOgqmGv84HUG2zWdXFkdNdjiAe8tJiwE=; b=MbUY+G14Sjn6hBKTM1KajBwc76H69Ipg7QFtSLzni0+xvUvBBVDtJ6biebLOSNPK1f ItUPRKPL/lC78RJF4RewKg2Y+AljPj2481WY7sRGbopT/aoW0W3mnkAzerGSPPWAHb+P TLfgpyIhq6sr4vTnd5OSJzT1/u/Ywdtz8HIEJ60E3yhFEPHy6Aq7MBklrjI1LQzq5ywu OsJuKLRZrZBIxDhPK2bSYmVAg9nCvdJLU4F8NhLQoWT0rApxFAf1tJi+QTxvnNmBErcy s4o0W9wCW37vWlhmotzISJICra8KRhG/9zqcreSf6eaVkN7MB9bgta8vdT2uhon8q8xY AVMw== X-Gm-Message-State: ALoCoQmXmsgX/3/ZNgmxnbbIh4z6kTnxTm8nbQVkHs5RRt2AJupcEOdBRNmLnl4rxYR9HKFmaAIr X-Received: by 10.180.94.3 with SMTP id cy3mr743164wib.7.1415371810332; Fri, 07 Nov 2014 06:50:10 -0800 (PST) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.43.129 with SMTP id w1ls207593lal.34.gmail; Fri, 07 Nov 2014 06:50:10 -0800 (PST) X-Received: by 10.112.168.97 with SMTP id zv1mr11936888lbb.6.1415371810093; Fri, 07 Nov 2014 06:50:10 -0800 (PST) Received: from mail-lb0-f170.google.com (mail-lb0-f170.google.com. [209.85.217.170]) by mx.google.com with ESMTPS id ro8si15308046lbb.75.2014.11.07.06.50.10 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Fri, 07 Nov 2014 06:50:10 -0800 (PST) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.217.170 as permitted sender) client-ip=209.85.217.170; Received: by mail-lb0-f170.google.com with SMTP id z12so2778530lbi.29 for ; Fri, 07 Nov 2014 06:50:10 -0800 (PST) X-Received: by 10.112.130.41 with SMTP id ob9mr11472015lbb.74.1415371809952; Fri, 07 Nov 2014 06:50:09 -0800 (PST) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.112.184.201 with SMTP id ew9csp210415lbc; Fri, 7 Nov 2014 06:50:08 -0800 (PST) X-Received: by 10.140.104.131 with SMTP id a3mr17315892qgf.31.1415371808340; Fri, 07 Nov 2014 06:50:08 -0800 (PST) Received: from ip-10-35-177-41.ec2.internal (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTPS id q6si17214796qas.32.2014.11.07.06.50.07 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Fri, 07 Nov 2014 06:50:08 -0800 (PST) Received-SPF: none (google.com: lng-odp-bounces@lists.linaro.org does not designate permitted sender hosts) client-ip=54.225.227.206; Received: from localhost ([127.0.0.1] helo=ip-10-35-177-41.ec2.internal) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XmkrW-0004F8-GX; Fri, 07 Nov 2014 14:50:06 +0000 Received: from mail-qa0-f41.google.com ([209.85.216.41]) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XmkrQ-0004EL-AS for lng-odp@lists.linaro.org; Fri, 07 Nov 2014 14:50:00 +0000 Received: by mail-qa0-f41.google.com with SMTP id s7so2412156qap.0 for ; Fri, 07 Nov 2014 06:49:55 -0800 (PST) X-Received: by 10.229.105.196 with SMTP id u4mr18013295qco.27.1415371795126; Fri, 07 Nov 2014 06:49:55 -0800 (PST) Received: from fedora1.holmesfamily.ws ([98.221.136.245]) by mx.google.com with ESMTPSA id q9sm8514504qat.21.2014.11.07.06.49.54 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 07 Nov 2014 06:49:54 -0800 (PST) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Fri, 7 Nov 2014 09:49:43 -0500 Message-Id: <1415371783-16010-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.1.0 MIME-Version: 1.0 X-Topics: patch Subject: [lng-odp] [PATCH] CONTRIBUTING: Improve the guidelines X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: , List-Help: , List-Subscribe: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: lng-odp-bounces@lists.linaro.org X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: mike.holmes@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.217.170 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 Clarify the ODP contribution process and add a common errors section. Signed-off-by: Mike Holmes --- CONTRIBUTING | 188 ++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 110 insertions(+), 78 deletions(-) diff --git a/CONTRIBUTING b/CONTRIBUTING index 1372ed9..2c4ad7f 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -1,81 +1,113 @@ - Contributing to the OpenDataplane (ODP) API - - The ODP API follows the linux kernel coding style [1] and code submission -process [2], albeit patch submissions are to be submitted to the ODP -linaro-networking mailing list [3] (not LKML, etc.). ODP targets the C99 standard -and code should refrain from using gcc specific extensions in the interface and -in the linux-generic implementation or examples. - - To certify you wrote the code, or otherwise have the right to pass it -on (presumably from a compatibly licensed project), we use the "Developer's -Certificate of Origin" (see [2]). Using this sign-off process, we are able to -keep track of compliance to our license (see LICENSE file). - - There are tools we use to maintain CodingStyle and other good programming -practice consistency, including type-checking without overuse of casts. - -(a) perform a one-time setup for the tools: - -semantic parser 'sparse' [4]: - - git clone git://git.kernel.org/pub/scm/devel/sparse/sparse.git - cd sparse - make - export PATH=$PATH:$PWD - -(b) when building, use sparse to check for stricter type checking than the -compiler: - - make CC=cgcc - -(c) create patches with git: - git format-patch --subject-prefix="PATCH" --find-renames HEAD^ - For prefixes see [3]. - -(d) Prior to submission, to style-check the patch 'file.patch', run: - - ./scripts/checkpatch.pl file.patch - - Note: A common issue that causes patches to fail checkpatch is the - presense of trailing whitespace. Emacs users can use the command: - - Meta-X delete-trailing-whitespace - - to scrub the file prior to saving to avoid these issues. Vim users - can accomplish the same with the command: - - :%s/\s\+$// - - Please ensure submitted patches are checkpatch clean before submitting - them to avoid having them automatically returned for rework. - -Documenting the code - - Allow doxygen to use all its default behaviors to identify tagged - information but where a doxygen tag must be specified use @ - - The first line is by default the brief summary. - - The next paragraph is by default the detailed summary - - Normal comment sections should be before the code block and start with - /** on its own line and finish with */ on its own line. The exception - to this rule is a case where the comment is very small, for example - /** macro description */ - #define SOME_MACRO 0 - - Commenting on the end of a line for macros and struct members is allowed using /**< */ for example - #define SOME_MACRO 0 /**< */ - - Files should start with a files description using @file - - Functions should specify their parameters with @param[in] and @param[out] +Contributing to the OpenDataplane (ODP) API +------------------------------------------- + +Table of content: +----------------- +1. New Development +2. ODP patch expectations as an open source project +3. Common Errors in Patch and Commit Messages +4. Documenting the code +5. References + +1. New Development +------------------ +ODP code shall be written with the kernel coding style [1]. +ODP code shall be documented using the doxygen style described in the +“Documenting the code” section. +Check patch script/checkpatch.pl shall be used before submitting a patch. + +2. ODP patch expectations as an open source project +---------------------- +While specific to the Linux kernel development, the following reference could +also be considered a general guide for any Open Source development [2] and is +relevant to ODP. Many of the guidelines in this ODP document are related to the +items in that information. +Pay particular attention to section 5.3 that talks about patch preparation. +The key thing to remember is to break up your changes into logical sections. +Otherwise you run the risk of not being able to even explain the purpose of a +change in the patch headers! +In addition section 5.4 explains the purpose of the Signed-off-by: tag line as +discussed in later parts of this document. Due to the importance of the +Signed-off-by: tag line a copy of the description follows: + +Signed-off-by: this is a developer's certification that he or she has +the right to submit the patch for inclusion into the [project]. It is +an agreement to the Developer's Certificate of Origin, the full text of +which can be found in [3] Documentation/SubmittingPatches. +Code without a proper signoff cannot be merged into the mainline. + +3. Common Errors in Patch and Commit Messages +--------------------------------------------- +- Avoid starting the summary line with a capital letter, unless the component + being referred to also begins with a capital letter. +- Don't have one huge patch, split your change into logical subparts. It's + easier to track down problems afterward using tools such as git bisect. It + also makes it easy for people to cherry-pick changes into things like stable + branches. +- Don't simply translate your change into English for a commit log. The log + "Change compare from zero to one" is bad because it describes only the code + change in the patch; we can see that from reading the patch itself. Let the + code tell the story of the mechanics of the change (as much as possible), and + let your comment tell the other details -- i.e. what the problem was, how it + manifested itself (symptoms), and if necessary, the justification for why the + fix was done in manner that it was. In other words, the long commit message + must describe *why* the change was needed (instead of what has changed). +- Don't start your commit log with "This patch..." -- we already know it is a + patch. +- Don't repeat your short log in the long log. If you really really don't have + anything new and informational to add in as a long log, then don't put a long + log at all. This should be uncommon -- i.e. the only acceptable cases for no + long log would be something like: + "Documentation/README: Fix spelling mistakes". +- Don't put absolute paths to source files that are specific to your site. +- Always use the most significant ramification of the change in the words of + your subject/shortlog. For example, don't say "fix compile warning in foo" + when the compiler warning was really telling us that we were dereferencing + complete garbage off in the weeds that could in theory cause an OOPS under + some circumstances. When people are choosing commits for backports to stable + or distro kernels, the shortlog will be what they use for an initial sorting + selection. If they see "Fix possible OOPS in...." then these people will look + closer, whereas they most likely will skip over simple warning fixes. +- Don't put in the full 20 or more lines of a backtrace when really it is just + the last 5 or so function calls that are relevant to the crash/fix. If the + entry point, or start of the trace is relevant (i.e. a syscall or similar), + you can leave that, and then replace a chunk of the intermediate calls in the + middle with a single [...] +- Don't include timestamps or other unnecessary information, unless they are + relevant to the situation (i.e. indicating an unacceptable delay in a driver + initialization etc.) +- Don't use links to temporary resources like pastebin and friends. The commit + message may be read long after this resource timed out. +- Don't reference mirrors, but instead always reference original authoritative + sources. +- Avoid punctuation in the short log. + +4. Documenting the code +--------------------------- +- Allow doxygen to use all its default behaviors to identify tagged + information but where a doxygen tag must be specified use @ +- The first line is by default the brief summary. +- The next paragraph is by default the detailed summary +- Doxygen shall generate the layout, no additional formatting should be inserted +- Normal comment sections should be before the code block and start with + /** on its own line and finish with */ on its own line. The exception + to this rule is a case where the comment is very small, for example + /** macro description */ + #define SOME_MACRO 0 +- Commenting on the end of a line for macros and struct members is allowed + using: + /**< */ for example + #define SOME_MACRO 0 /**< */ +- Files should start with a files description using @file +- Functions should specify their parameters with @param[in] and @param[out] +- Functions return values should all be specified using @return or @retval +- There should be no doxygen warnings or errors generated. + +5. References +---------------- +[1] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle +[2] http://ldn.linuxfoundation.org/book/how-participate-linux-community +[3] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches - Functions return values should all be specified using @return - There should be no doxygen warnings or errors generated. -[1] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle -[2] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches -[3] refer to README file. -[4] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/sparse.txt