From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 26F6091E7 for ; Thu, 15 Oct 2015 18:51:38 +0200 (CEST) Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga103.jf.intel.com with ESMTP; 15 Oct 2015 09:51:37 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.17,686,1437462000"; d="scan'208";a="581507251" Received: from irvmail001.ir.intel.com ([163.33.26.43]) by FMSMGA003.fm.intel.com with ESMTP; 15 Oct 2015 09:51:37 -0700 Received: from sivswdev02.ir.intel.com (sivswdev02.ir.intel.com [10.237.217.46]) by irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id t9FGpZ3K010376; Thu, 15 Oct 2015 17:51:35 +0100 Received: from sivswdev02.ir.intel.com (localhost [127.0.0.1]) by sivswdev02.ir.intel.com with ESMTP id t9FGpZwJ019894; Thu, 15 Oct 2015 17:51:35 +0100 Received: (from jmcnam2@localhost) by sivswdev02.ir.intel.com with id t9FGpZDS019889; Thu, 15 Oct 2015 17:51:35 +0100 From: John McNamara To: dev@dpdk.org Date: Thu, 15 Oct 2015 17:51:33 +0100 Message-Id: <1444927893-19845-2-git-send-email-john.mcnamara@intel.com> X-Mailer: git-send-email 1.7.4.1 In-Reply-To: <1444927893-19845-1-git-send-email-john.mcnamara@intel.com> References: <1444927893-19845-1-git-send-email-john.mcnamara@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] =?utf-8?q?=5BPATCH=5D_doc=3A_add_contributors_guide?= X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 15 Oct 2015 16:51:39 -0000 Add a document to explain the DPDK patch submission and review process. Signed-off-by: John McNamara --- doc/guides/contributing/index.rst | 1 + doc/guides/contributing/patches.rst | 309 ++++++++++++++++++++++++++++++++++++ 2 files changed, 310 insertions(+) create mode 100644 doc/guides/contributing/patches.rst diff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst index 561427b..f49ca88 100644 --- a/doc/guides/contributing/index.rst +++ b/doc/guides/contributing/index.rst @@ -9,3 +9,4 @@ Contributor's Guidelines design versioning documentation + patches diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst new file mode 100644 index 0000000..e5d28d5 --- /dev/null +++ b/doc/guides/contributing/patches.rst @@ -0,0 +1,309 @@ +.. submitting_patches: + +Contributing Code to DPDK +========================= + +This document outlines the guidelines for submitting code to DPDK. + +The DPDK development process is modeled (loosely) on the Linux Kernel development model so it is worth reading the +Linux kernel guide on submitting patches: +`How to Get Your Change Into the Linux Kernel `_. +The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines. + + +The DPDK Development Process +----------------------------- + +The DPDK development process has the following features: + +* The code is hosted in a public git repository. +* There is a mailing list where developers submit patches. +* There are maintainers for hierarchical components. +* Patches are reviewed publicly on the mailing list. +* Successfully reviewed patches are merged to the master branch of the repository. + +The mailing list for DPDK development is `dev@dpkg.org `_. +Contributors will need to `register for the mailing list `_ in order to submit patches. +It is also worth registering for the DPDK `Patchwork `_ + +There are also DPDK mailing lists for: + +* users: `general usage questions `_. +* announce: `release announcements `_ (also forwarded to the dev list). +* dts: `test suite reviews and discussions `_. +* test-reports: `test reports `_ (from continuous integration testing). + +The development process requires some familiarity with the ``git`` version control system. +Refer to the `Pro Git Book `_ for further information. + + +Getting the Source Code +----------------------- + +The source code can be cloned using either of the following:: + + git clone git://dpdk.org/dpdk + + git clone http://dpdk.org/git/dpdk + +You can also `browse the source code `_ online. + + +Make your Changes +----------------- + +Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines and requirements: + +* Follow the :ref:`coding_style` guidelines. + +* If you add new files or directories you should add your name to the ``MAINTAINERS`` file. + +* If your changes add new external functions then they should be added to the local ``version.map`` file. + See the :doc:`Guidelines for ABI policy and versioning `. + +* Most changes will require an addition to the release notes in ``doc/guides/rel_notes/``. + See the :ref:`Release Notes section of the Documentation Guidelines ` for details. + +* Don’t break compilation between commits with forward dependencies. + Each commit should compile on its own to allow for ``git bisect`` and continuous integration testing. + +* Add tests to the the ``app/test`` unit test framework where possible. + +* Add documentation, if required, in the form of Doxygen comments or a User Guide in RST format. + See the :ref:`Documentation Guidelines `. + +Once the changes have been made you should commit them to your local repo. +The commits should be separated into logical patches in a patchset. +In general commits should be separated based on their directory such as ``lib``, ``drivers``, ``scripts`` although +some of these, such as ``drivers`` may require finer grained separation. +The easiest way of determining this is to do a ``git log`` on changed or similar files. + +Example of a logical patchset separation:: + + [patch 1/6] ethdev: add support for ieee1588 timestamping + [patch 2/6] e1000: add support for ieee1588 timestamping + [patch 3/6] ixgbe: add support for ieee1588 timestamping + [patch 4/6] i40e: add support for ieee1588 timestamping + [patch 5/6] app/testpmd: refactor ieee1588 forwarding + [patch 6/6] doc: document ieee1588 forwarding mode + + +The component separation will also be used in the subject line of the commit message, see below. +The required format of the commit messages is shown in the next sections. + + +Commit Messages: Subject Line +----------------------------- + +The first, summary, line of the git commit message becomes the subject line of the patch email. +Here are some guidelines for the summary line: + +* The summary line should be around 50 characters. + +* The summary line should be lowercase. + +* It should be prefixed with the component name (use git log to check existing components). + For example:: + + config: enable same drivers options for linux and bsd + + ixgbe: fix offload config option name + +* Use the imperative of the verb (like instructions to the code base). + For example:: + + ixgbe: fix bug in xyz + + ixgbe: add refcount to foo struct + +* Don't add a period/full stop to the subject line or you will end up two in the patch name: ``dpdk_description..patch``. + +The actual email subject line should be prefixed by ``[PATCH]`` and the version, if greater than v1, +for example: ``PATCH v2``. +The is generally added by ``git send-email`` or ``git format-patch``, see below. + +If you are submitting a RFC draft of a feature you can use ``[RFC]`` instead of ``[PATCH]``. + + +Commit Messages: Body +--------------------- + +Here are some guidelines for the body of a commit message: + +* You must provide a body to the commit message after the subject/summary line. + Do not leave it blank. + +* The body of the message should describe the issue being fixed or the feature being added. + It is important to provide enough information to allow a reviewer to understand the purpose of the patch. + +* The commit message must end with a ``Signed-off-by:`` line which is added using:: + + git commit --signoff # or -s + + The purpose of the signoff is explained in the + `Developer's Certificate of Origin `_ + section of the Linux kernel guidelines. + + .. Note:: + + All developers must ensure that they have read and understood the + Developer's Certificate of Origin section of the documentation prior + to applying the signoff and submitting a patch. + +* The signoff must be a real name and not an alias or nickname. + More than one signoff is allowed. + +* The text of the commit message should be wrapped at 72 characters. + +* When fixing a regression, it is a good idea to reference the id of the commit which introduced the bug. + You can generate the required text as follows:: + + git log -1 COMMIT_ID --abbrev=12 --format='Fixes: %h ("%s")' + + Fixes: a4024448efa6 ("i40e: add ieee1588 timestamping") + +* When fixing an error or warning it is useful to add the error message or output. + +* Use correct capitalization, punctuation and spelling. + +In addition to the ``Signed-off-by:`` name the commit messages can also have one or more of the following: + +* ``Reported-by:`` The reporter of the issue. +* ``Tested-by:`` The tester of the change. +* ``Reviewed-by:`` The reviewer of the change. +* ``Suggested-by:`` The person who suggested the change. + + +Creating Patches +---------------- + +It is possible to send patches directly from git but for new contributors it is recommended to generate the +patches with ``git format-patch`` and then when everything looks okay, and the patches have been checked, to +send them with ``git send-mail``. + +Here are some examples of using ``git format-patch`` to generate patches: + +.. code-block:: console + + # Generate a patch from the last commit. + git format-patch -1 + + # Generate a patch from the last 3 commits. + git format-patch -3 + + # Generate the patches in a directory. + git format-patch -3 -o ~/patch/ + + # Add a cover letter to explain a patchset. + git format-patch -3 -o --cover-letter + + # Add a prefix with a version number. + git format-patch -3 -o --subject-prefix 'PATCH v2' + + +Cover letters are useful for explaining a patchset. +Smaller notes can be put inline in the patch after the ``---`` separator, for example:: + + Subject: [PATCH] fm10k/base: add FM10420 device ids + + Add the device ID for Boulder Rapids and Atwood Channel to enable + drivers to support those devices. + + Signed-off-by: Wang Xiao W + --- + + ADD NOTES HERE. + + drivers/net/fm10k/base/fm10k_api.c | 6 ++++++ + drivers/net/fm10k/base/fm10k_type.h | 6 ++++++ + 2 files changed, 12 insertions(+) + ... + +Version 2 and later of a patchset should also include a short log of the changes so the reviewer knows what has changed. +This can go either in the cover letter on the annotations. +For example:: + + v3: + * Fixed issued with version.map. + + v2: + * Added i40e support. + * Renamed ethdev functions from rte_eth_ieee15888_*() to rte_eth_timesync_*() + since 802.1AS can be supported through the same interfaces. + + +Checking the Patches +-------------------- + +Patches should be checked for formatting and syntax issues using the Linux scripts tool ``checkpatch``. + +The ``checkpatch`` utility can be obtained by cloning, and periodically, updating the Linux kernel sources. + +The kernel guidelines that are tested by ``checkpatch`` don't match the DPDK Coding Style guidelines exactly but +they provide a good indication of conformance. +Warnings about not using kernel data types or about split strings can be ignored:: + + /path/checkpatch.pl --ignore PREFER_KERNEL_TYPES,SPLIT_STRING -q files*.patch + + +Sending Patches +--------------- + +Patches should be sent to the mailing list using ``git send-email``. +This will require a working and configured ``sendmail`` or similar application. +See the `Git send-mail `_ documentation for more details. + +The patches should be sent to ``dev@dpdk.org``:: + + git send-email --to dev@dpdk.org 000*.patch + +If the patches are a change to existing files then you should CC the maintainer(s) of the changed files. +The appropriate maintainer can be found in the ``MAINTAINERS`` file:: + + git send-email --to dev@dpdk.org --cc maintainer@some.org 000*.patch + +You can test the emails by sending it to yourself or with the ``--dry-run`` option. + +If the patch is in relation to a previous email thread you can add it to the same thread using the Message ID:: + + git send-email --to dev@dpdk.org --in-reply-to <1234-foo@bar.com> 000*.patch + +The Message ID can be found in the raw text of emails or at the top of each Patchwork patch, +`for example `_. + + +Once submitted your patches will appear on the mailing list and in Patchwork. + +Experienced commiters may send patches directly with ``git send-email`` without the ``git format-patch`` step. + + +The Review Process +------------------ + +The more work you put into the previous steps the easier it will be to get a patch accepted. + +The general cycle for patch review and acceptance is: + +#. Submit the patch. + +#. Wait for review comments. While you are waiting review some other patches. + +#. Fix the review comments and submit a ``v n+1`` patchset:: + + git format-patch -3 -o --subject-prefix 'PATCH v2' + +#. Update Patchwork to mark your previous patches as "Superseded". + +#. If the patch is deemed suitable for merging by the relevant maintainer(s) or other developers they will ``ack`` + the patch with an email that includes something like:: + + Acked-by: Alex Smith + + **Note**: When acking patches please remove as much of the text of the patch email as possible. + It is generally best to delete everything after the ``Signed-off-by:`` line. + +#. If the patch isn't deemed suitable based on being out of scope or conflicting with existing functionality + it may receive a ``nack``. + In this case you will need to make a more convincing technical argument in favor of your patches. + +#. Acked patches will be merged in the next merge window. -- 1.8.1.4