From patchwork Mon Jun 13 16:04:55 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 69896 Delivered-To: patch@linaro.org Received: by 10.140.106.246 with SMTP id e109csp1617397qgf; Mon, 13 Jun 2016 09:05:11 -0700 (PDT) X-Received: by 10.200.33.229 with SMTP id 34mr15261210qtz.100.1465833911462; Mon, 13 Jun 2016 09:05:11 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id j11si15571018qhd.94.2016.06.13.09.05.10; Mon, 13 Jun 2016 09:05:11 -0700 (PDT) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=pass (p=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 4238168545; Mon, 13 Jun 2016 16:05:10 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id DEC42616EF; Mon, 13 Jun 2016 16:05:03 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 287926853F; Mon, 13 Jun 2016 16:05:01 +0000 (UTC) Received: from mail-oi0-f45.google.com (mail-oi0-f45.google.com [209.85.218.45]) by lists.linaro.org (Postfix) with ESMTPS id DB22161565 for ; Mon, 13 Jun 2016 16:04:59 +0000 (UTC) Received: by mail-oi0-f45.google.com with SMTP id w5so135413102oib.2 for ; Mon, 13 Jun 2016 09:04:59 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=JBIk08XFZiplFDAyeJ+BIJypVdbn8qvzxSg3Sn/RUoo=; b=jZ9j2kZGfxCqpeoVXU7OgkrwwQZz6Bc+xWmJYHjXAiP3inDtBC0EkHmS4j7B60DxSq MGnWoqucNXCZjJkws2LGlf1oP3WuftNJksYKJVcCYcqeHtWdwSP75JfwTuSfolH4cotV rkgx0kkBQKq0fLvcJKE6Xwf5nBUaASbxRXUpyPblAGTQA8jtMMquFcUDotMyzKvBILwv GEjSOgCHJFfqN7T1DZbLFQT0fQNqyR+7nG9CsNENcRR9Qt1a4ipMTL+xq2oi76dDIVTZ Hr3o4QYVLk1EBecCa7YqllUnN05PorpEeicVtU1SQS43ZYLMXxIWZF5xKBZgb1dJLdhY gNaA== X-Gm-Message-State: ALyK8tJWcGcYsFAtMOsfexx+Ou/HNSki1uGaw3zPpUwMiq4DCNe0kXytHKcw89ktR7MyBByyYKc= X-Received: by 10.202.65.133 with SMTP id o127mr8071799oia.43.1465833899168; Mon, 13 Jun 2016 09:04:59 -0700 (PDT) Received: from localhost.localdomain (cpe-66-68-129-43.austin.res.rr.com. [66.68.129.43]) by smtp.gmail.com with ESMTPSA id f199sm11871560oih.2.2016.06.13.09.04.58 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 13 Jun 2016 09:04:58 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Mon, 13 Jun 2016 11:04:55 -0500 Message-Id: <1465833895-14871-1-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.7.4 X-Topics: patch Subject: [lng-odp] [PATCH] contributing: add user agreement and short log conventions X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Signed-off-by: Bill Fischofer --- CONTRIBUTING | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING b/CONTRIBUTING index a81fd8d..b0b2781 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -11,12 +11,27 @@ in understanding the contributing requirements for ODP This document is intended to guide a new application developer in understanding the contributing requirements for ODP +== Contributor's Agreement +ODP is an open source project that follows the +https://opensource.org/licenses/BSD-3-Clause[BSD 3 Clause] license. Every +contributor to ODP must agree to comply by these licensing terms as well as +assert that they have the right to contribute the code they submit to the +project. No patches will be considered for acceptance without the contributor +having first executed either an +http://www.opendataplane.org/contributor/individual/[Individual Contributor +License Agreement] or being a member of an orgnaization that has executed +a http://www.opendataplane.org/contributor/corporate/[Corporate Contributor +License Agreement]. + +These agreements are a one-time requirement and take only a few minutes to +perform by click-through. + == New Development ODP code shall be written with the kernel coding style https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle[Kernel Coding Style] ODP code shall be documented using the doxygen style described in the -"Documenting the code" section. +<> section. Check patch script/checkpatch.pl shall be used before submitting a patch. == ODP patch expectations as an open source project @@ -42,6 +57,120 @@ which can be found in https://git.kernel.org/cgit/linux/kernel/git/torvalds/linu Code without a proper signoff cannot be merged into the mainline. +== Short Log and Long Log Conventions +For ease of patch management, every submitted patch must have a short log +entry. The short log is a one-line summary of the patch and says where it +is intended to be applied and (briefly) its purpose. Following the short +log, submitters are free to add additional detail in the long log. Long log +entries are encouraged when appropriate, but there are no specific requirements +governing their structure or contents other than that they be relvant and +useful to potential reviewers in understanding the purpose and rationale +for the patch. + +=== Short log format +ODP requires that the short log be a single line not exceeding 80 characters, +be composed entirely in lower case, and be structured as follows: + +`area: component: brief description` + +Note that a single colon (:) should be used to separate each section of the +short log and be followed by a single space before beginning the next section. + +Area identifies the functional area that this patch addresses and in general +says where in the directory hierarchy the patch is intended to apply. This +should be taken from the following list: + +api:: +Patch adds, deletes, or changes an ODP API. Any patch that applies to the +`include` directory or its descendants is considered an API patch and must +be identified as such. Moreover, any patch series containing an api patch +must be identified in the patch's `--subject-prefix` as API-NEXT. + +doc:: +Patch applies to the ODP documentation library contained in the `doc` directory + +example:: +Patch applies to the ODP examples contained in the `example` directory. + +helper:: +Patch applies to the ODP helper library contained in the `helper` directory. + +performance:: +Patch applies to the ODP performance test suite contained in the +`test/performance` directory. + +linux-generic:: +linux-gen:: +l-g:: +Patch applies to the odp-linux reference implementation, specifically the +`platform/linux-generic/` directory that contains that implementation. The +alternate forms `linux-gen` or `l-g` may be used to conserve line space if +desired. + +validation:: +Patch applies to the ODP validation test suite contained in the +`test/validation` directory. + +Any other patch that applies to some other top-level directory or file should +use that directory or file name as its area. + +The component portion of the short log identifies the ODP component that this +patch applies to. A component is required unless the area is a single file, in +which case it may be omitted. Components should be selected from the following +list: + +buffer:: +Buffers and buffer processing. + +classification:: +cls:: +Classification. `cls` may be used as an abbreviation for space if desired. + +crypto: +Crypto. + +pktio:: +Packet I/O (pktio) and its related sub-components + +packet:: +Packets and packet processing. + +pool:: +Buffer pools and related processing. + +queue:: +Queues and related processing. + +scheduler:: +sched:: +Scheduler and related processing. + +time:: +Time. + +timer:: +Timers and related processing. + +tm:: +Traffic Manager and related processing. + +Following the component the rest of the short log should describe the purpose +of this patch. + +=== Examples +To illustrate, here are some examples of good and bad short logs: + +Good:: +* `api: pool: add new foo attribute to pools` +* `linux-generic: pool: implement new foo attribute for pools` +* `validation: pool: test new foo attribute for pools` + +Bad:: +* `fix something` (doesn't follow required format) +* `api: propose a new api` (missing component) +* `validation: pool: a description that rambles on and on and never gets to +the point` + == Common Errors in Patch and Commit Messages - Avoid starting the summary line with a capital letter, unless the component @@ -92,7 +221,7 @@ Code without a proper signoff cannot be merged into the mainline. - References to wikipedia are not permitted. -=== Documenting the code +=== Documenting the Code - Allow doxygen to use all its default behaviors to identify tagged information but where a doxygen tag must be specified use @