Patch Detail

HTTP 200 OK
Allow: GET, PUT, PATCH, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "id": 7762,
    "url": "https://patches.dpdk.org/api/patches/7762/?format=api",
    "web_url": "https://patches.dpdk.org/project/dpdk/patch/1445338986-28015-1-git-send-email-john.mcnamara@intel.com/",
    "project": {
        "id": 1,
        "url": "https://patches.dpdk.org/api/projects/1/?format=api",
        "name": "DPDK",
        "link_name": "dpdk",
        "list_id": "dev.dpdk.org",
        "list_email": "dev@dpdk.org",
        "web_url": "http://core.dpdk.org",
        "scm_url": "git://dpdk.org/dpdk",
        "webscm_url": "http://git.dpdk.org/dpdk",
        "list_archive_url": "https://inbox.dpdk.org/dev",
        "list_archive_url_format": "https://inbox.dpdk.org/dev/{}",
        "commit_url_format": ""
    },
    "msgid": "<1445338986-28015-1-git-send-email-john.mcnamara@intel.com>",
    "list_archive_url": "https://inbox.dpdk.org/dev/1445338986-28015-1-git-send-email-john.mcnamara@intel.com",
    "date": "2015-10-20T11:03:06",
    "name": "[dpdk-dev,v2] doc: add contributors guide",
    "commit_ref": null,
    "pull_url": null,
    "state": "superseded",
    "archived": true,
    "hash": "1fd1aa5638a5956fe4c5898a08a29624c3f80be0",
    "submitter": {
        "id": 154,
        "url": "https://patches.dpdk.org/api/people/154/?format=api",
        "name": "John McNamara",
        "email": "john.mcnamara@intel.com"
    },
    "delegate": null,
    "mbox": "https://patches.dpdk.org/project/dpdk/patch/1445338986-28015-1-git-send-email-john.mcnamara@intel.com/mbox/",
    "series": [],
    "comments": "https://patches.dpdk.org/api/patches/7762/comments/",
    "check": "pending",
    "checks": "https://patches.dpdk.org/api/patches/7762/checks/",
    "tags": {},
    "related": [],
    "headers": {
        "Return-Path": "<dev-bounces@dpdk.org>",
        "X-Original-To": "patchwork@dpdk.org",
        "Delivered-To": "patchwork@dpdk.org",
        "Received": [
            "from [92.243.14.124] (localhost [IPv6:::1])\n\tby dpdk.org (Postfix) with ESMTP id A1C6C8E80;\n\tTue, 20 Oct 2015 13:03:18 +0200 (CEST)",
            "from mga09.intel.com (mga09.intel.com [134.134.136.24])\n\tby dpdk.org (Postfix) with ESMTP id B1C048E7A\n\tfor <dev@dpdk.org>; Tue, 20 Oct 2015 13:03:15 +0200 (CEST)",
            "from fmsmga003.fm.intel.com ([10.253.24.29])\n\tby orsmga102.jf.intel.com with ESMTP; 20 Oct 2015 04:03:14 -0700",
            "from irvmail001.ir.intel.com ([163.33.26.43])\n\tby FMSMGA003.fm.intel.com with ESMTP; 20 Oct 2015 04:03:13 -0700",
            "from sivswdev02.ir.intel.com (sivswdev02.ir.intel.com\n\t[10.237.217.46])\n\tby irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id\n\tt9KB3CpL021428; Tue, 20 Oct 2015 12:03:13 +0100",
            "from sivswdev02.ir.intel.com (localhost [127.0.0.1])\n\tby sivswdev02.ir.intel.com with ESMTP id t9KB3CF9028083;\n\tTue, 20 Oct 2015 12:03:12 +0100",
            "(from jmcnam2@localhost)\n\tby sivswdev02.ir.intel.com with  id t9KB3CiD028079;\n\tTue, 20 Oct 2015 12:03:12 +0100"
        ],
        "X-ExtLoop1": "1",
        "X-IronPort-AV": "E=Sophos;i=\"5.17,707,1437462000\"; d=\"scan'208\";a=\"584474809\"",
        "From": "John McNamara <john.mcnamara@intel.com>",
        "To": "dev@dpdk.org",
        "Date": "Tue, 20 Oct 2015 12:03:06 +0100",
        "Message-Id": "<1445338986-28015-1-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_v2=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 <dev.dpdk.org>",
        "List-Unsubscribe": "<http://dpdk.org/ml/options/dev>,\n\t<mailto:dev-request@dpdk.org?subject=unsubscribe>",
        "List-Archive": "<http://dpdk.org/ml/archives/dev/>",
        "List-Post": "<mailto:dev@dpdk.org>",
        "List-Help": "<mailto:dev-request@dpdk.org?subject=help>",
        "List-Subscribe": "<http://dpdk.org/ml/listinfo/dev>,\n\t<mailto:dev-request@dpdk.org?subject=subscribe>",
        "Errors-To": "dev-bounces@dpdk.org",
        "Sender": "\"dev\" <dev-bounces@dpdk.org>"
    },
    "content": "Add a document to explain the DPDK patch submission and review process.\n\nSigned-off-by: John McNamara <john.mcnamara@intel.com>\n---\n\nv2:\n* Fixes for mailing list comments.\n* Fix for broken link target.\n\n doc/guides/contributing/documentation.rst |   2 +-\n doc/guides/contributing/index.rst         |   1 +\n doc/guides/contributing/patches.rst       | 327 ++++++++++++++++++++++++++++++\n 3 files changed, 329 insertions(+), 1 deletion(-)\n create mode 100644 doc/guides/contributing/patches.rst",
    "diff": "diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst\nindex 7c1eb41..0e37f01 100644\n--- a/doc/guides/contributing/documentation.rst\n+++ b/doc/guides/contributing/documentation.rst\n@@ -1,4 +1,4 @@\n-.. doc_guidelines:\n+.. _doc_guidelines:\n \n DPDK Documentation Guidelines\n =============================\ndiff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst\nindex 561427b..f49ca88 100644\n--- a/doc/guides/contributing/index.rst\n+++ b/doc/guides/contributing/index.rst\n@@ -9,3 +9,4 @@ Contributor's Guidelines\n     design\n     versioning\n     documentation\n+    patches\ndiff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst\nnew file mode 100644\nindex 0000000..7166014\n--- /dev/null\n+++ b/doc/guides/contributing/patches.rst\n@@ -0,0 +1,327 @@\n+.. submitting_patches:\n+\n+Contributing Code to DPDK\n+=========================\n+\n+This document outlines the guidelines for submitting code to DPDK.\n+\n+The DPDK development process is modeled (loosely) on the Linux Kernel development model so it is worth reading the\n+Linux kernel guide on submitting patches:\n+`How to Get Your Change Into the Linux Kernel <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_.\n+The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines.\n+\n+\n+The DPDK Development Process\n+-----------------------------\n+\n+The DPDK development process has the following features:\n+\n+* The code is hosted in a public git repository.\n+* There is a mailing list where developers submit patches.\n+* There are maintainers for hierarchical components.\n+* Patches are reviewed publicly on the mailing list.\n+* Successfully reviewed patches are merged to the master branch of the repository.\n+\n+The mailing list for DPDK development is `dev@dpkg.org <http://dpdk.org/ml/archives/dev/>`_.\n+Contributors will need to `register for the mailing list <http://dpdk.org/ml/listinfo/dev>`_ in order to submit patches.\n+It is also worth registering for the DPDK `Patchwork <http://dpdk.org/dev/patchwxispork/project/dpdk/list/>`_\n+\n+The development process requires some familiarity with the ``git`` version control system.\n+Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information.\n+\n+\n+Getting the Source Code\n+-----------------------\n+\n+The source code can be cloned using either of the following::\n+\n+    git clone git://dpdk.org/dpdk\n+\n+    git clone http://dpdk.org/git/dpdk\n+\n+\n+Make your Changes\n+-----------------\n+\n+Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines and requirements:\n+\n+* Follow the :ref:`coding_style` guidelines.\n+\n+* If you add new files or directories you should add your name to the ``MAINTAINERS`` file.\n+\n+* New external functions should be added to the local ``version.map`` file.\n+  See the :doc:`Guidelines for ABI policy and versioning </contributing/versioning>`.\n+\n+* Important changes will require an addition to the release notes in ``doc/guides/rel_notes/``.\n+  See the :ref:`Release Notes section of the Documentation Guidelines <doc_guidelines>` for details.\n+\n+* Run ``make test`` and ``make examples`` to ensure the changes haven't broken existing code.\n+\n+* Don’t break compilation between commits with forward dependencies in a patchset.\n+  Each commit should compile on its own to allow for ``git bisect`` and continuous integration testing.\n+\n+* Add tests to the the ``app/test`` unit test framework where possible.\n+\n+* Add documentation, if relevant, in the form of Doxygen comments or a User Guide in RST format.\n+  See the :ref:`Documentation Guidelines <doc_guidelines>`.\n+\n+Once the changes have been made you should commit them to your local repo.\n+\n+For small changes, that do not require specific explanations, it is better to keep things together in the\n+same patch.\n+Larger changes that require different explanations should be separated into logical patches in a patchset.\n+A good way of thinking about whether a patch should be split is to consider whether the change could be\n+applied without dependencies as a backport.\n+\n+As a guide to how patches should be structured run ``git log`` on similar files.\n+\n+\n+Commit Messages: Subject Line\n+-----------------------------\n+\n+The first, summary, line of the git commit message becomes the subject line of the patch email.\n+Here are some guidelines for the summary line:\n+\n+* The summary line must capture the area and the impact of the change.\n+\n+* The summary line should be around 50 characters.\n+\n+* The summary line should be lowercase apart from acronyms.\n+\n+* It should be prefixed with the component name (use git log to check existing components).\n+  For example::\n+\n+     config: enable same drivers options for linux and bsd\n+\n+     ixgbe: fix offload config option name\n+\n+* Use the imperative of the verb (like instructions to the code base).\n+  For example::\n+\n+     ixgbe: fix rss in 32 bit\n+\n+* Don't add a period/full stop to the subject line or you will end up two in the patch name: ``dpdk_description..patch``.\n+\n+The actual email subject line should be prefixed by ``[PATCH]`` and the version, if greater than v1,\n+for example: ``PATCH v2``.\n+The is generally added by ``git send-email`` or ``git format-patch``, see below.\n+\n+If you are submitting an RFC draft of a feature you can use ``[RFC]`` instead of ``[PATCH]``.\n+An RFC patch doesn't have to be complete.\n+It is intended as a way of getting early feedback.\n+\n+\n+Commit Messages: Body\n+---------------------\n+\n+Here are some guidelines for the body of a commit message:\n+\n+* The body of the message should describe the issue being fixed or the feature being added.\n+  It is important to provide enough information to allow a reviewer to understand the purpose of the patch.\n+\n+* When the change is obvious the body can be blank, apart from the signoff.\n+\n+* The commit message must end with a ``Signed-off-by:`` line which is added using::\n+\n+      git commit --signoff # or -s\n+\n+  The purpose of the signoff is explained in the\n+  `Developer's Certificate of Origin <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_\n+  section of the Linux kernel guidelines.\n+\n+  .. Note::\n+\n+     All developers must ensure that they have read and understood the\n+     Developer's Certificate of Origin section of the documentation prior\n+     to applying the signoff and submitting a patch.\n+\n+* The signoff must be a real name and not an alias or nickname.\n+  More than one signoff is allowed.\n+\n+* The text of the commit message should be wrapped at 72 characters.\n+\n+* When fixing a regression, it is a good idea to reference the id of the commit which introduced the bug.\n+  You can generate the required text using the following git alias::\n+\n+     git alias: fixline = log -1 --abbrev=12 --format='Fixes: %h (\\\"%s\\\")'\n+\n+\n+  The ``Fixes:`` line can then be added to the commit message::\n+\n+     doc: fix vhost sample parameter\n+\n+     Update the docs to reflect removed dev-index.\n+\n+     Fixes: 17b8320a3e11 (\"vhost: remove index parameter\")\n+\n+     Signed-off-by: Changchun Ouyang <changchun.ouyang@intel.com>\n+\n+* When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.\n+\n+* Use correct capitalization, punctuation and spelling.\n+\n+In addition to the ``Signed-off-by:`` name the commit messages can also have one or more of the following:\n+\n+* ``Reported-by:`` The reporter of the issue.\n+* ``Tested-by:`` The tester of the change.\n+* ``Reviewed-by:`` The reviewer of the change.\n+* ``Suggested-by:`` The person who suggested the change.\n+* ``Acked-by:`` When a previous version of the patch was acked and the ack is still relevant.\n+\n+\n+Creating Patches\n+----------------\n+\n+It is possible to send patches directly from git but for new contributors it is recommended to generate the\n+patches with ``git format-patch`` and then when everything looks okay, and the patches have been checked, to\n+send them with ``git send-mail``.\n+\n+Here are some examples of using ``git format-patch`` to generate patches:\n+\n+.. code-block:: console\n+\n+   # Generate a patch from the last commit.\n+   git format-patch -1\n+\n+   # Generate a patch from the last 3 commits.\n+   git format-patch -3\n+\n+   # Generate the patches in a directory.\n+   git format-patch -3 -o ~/patch/\n+\n+   # Add a cover letter to explain a patchset.\n+   git format-patch -3 -o --cover-letter\n+\n+   # Add a prefix with a version number.\n+   git format-patch -3 -o --subject-prefix 'PATCH v2'\n+\n+\n+Cover letters are useful for explaining a patchset and help to generate a logical threading to the patches.\n+Smaller notes can be put inline in the patch after the ``---`` separator, for example::\n+\n+   Subject: [PATCH] fm10k/base: add FM10420 device ids\n+\n+   Add the device ID for Boulder Rapids and Atwood Channel to enable\n+   drivers to support those devices.\n+\n+   Signed-off-by: Wang Xiao W <xiao.w.wang@intel.com>\n+   ---\n+\n+   ADD NOTES HERE.\n+\n+    drivers/net/fm10k/base/fm10k_api.c  | 6 ++++++\n+    drivers/net/fm10k/base/fm10k_type.h | 6 ++++++\n+    2 files changed, 12 insertions(+)\n+   ...\n+\n+Version 2 and later of a patchset should also include a short log of the changes so the reviewer knows what has changed.\n+This can be added to the cover letter or the annotations.\n+For example::\n+\n+   v3:\n+   * Fixed issued with version.map.\n+\n+   v2:\n+   * Added i40e support.\n+   * Renamed ethdev functions from rte_eth_ieee15888_*() to rte_eth_timesync_*()\n+     since 802.1AS can be supported through the same interfaces.\n+\n+\n+Checking the Patches\n+--------------------\n+\n+Patches should be checked for formatting and syntax issues using the Linux scripts tool ``checkpatch``.\n+\n+The ``checkpatch`` utility can be obtained by cloning, and periodically, updating the Linux kernel sources.\n+\n+The kernel guidelines tested by ``checkpatch`` don't match the DPDK Coding Style guidelines exactly but\n+they provide a good indication of conformance.\n+Warnings about kernel data types or about split strings can be ignored::\n+\n+   /path/checkpatch.pl --ignore PREFER_KERNEL_TYPES,SPLIT_STRING -q files*.patch\n+\n+Ensure that the code compiles with ``gcc`` and ``clang``::\n+\n+   make T=x86_64-native-linuxapp-gcc   install\n+   make T=x86_64-native-linuxapp-clang install\n+\n+Confirm that the changes haven't broken any existing code by using ``make test`` and ``make examples``.\n+\n+\n+Sending Patches\n+---------------\n+\n+Patches should be sent to the mailing list using ``git send-email``.\n+You can configure an external SMTP with something like the following::\n+\n+   [sendemail]\n+       smtpuser = name@domain.com\n+       smtpserver = smtp.domain.com\n+       smtpserverport = 465\n+       smtpencryption = ssl\n+\n+See the `Git send-mail <https://git-scm.com/docs/git-send-email>`_ documentation for more details.\n+\n+The patches should be sent to ``dev@dpdk.org``.\n+If the patches are a change to existing files then you should send them TO the maintainer(s) and CC ``dev@dpdk.org``.\n+The appropriate maintainer can be found in the ``MAINTAINERS`` file::\n+\n+   git send-email --to maintainer@some.org --cc dev@dpdk.org 000*.patch\n+\n+New additions can be sent without a maintainer::\n+\n+   git send-email --to dev@dpdk.org 000*.patch\n+\n+You can test the emails by sending it to yourself or with the ``--dry-run`` option.\n+\n+If the patch is in relation to a previous email thread you can add it to the same thread using the Message ID::\n+\n+   git send-email --to dev@dpdk.org --in-reply-to <1234-foo@bar.com> 000*.patch\n+\n+The Message ID can be found in the raw text of emails or at the top of each Patchwork patch,\n+`for example <http://dpdk.org/dev/patchwork/patch/7646/>`_.\n+Shallow threading (``--thread --no-chain-reply-to``) is preferred for a patch series.\n+\n+Once submitted your patches will appear on the mailing list and in Patchwork.\n+\n+Experienced committers may send patches directly with ``git send-email`` without the ``git format-patch`` step.\n+The options ``--annotate`` and ``confirm = always`` are recommended for checking patches before sending.\n+\n+\n+The Review Process\n+------------------\n+\n+The more work you put into the previous steps the easier it will be to get a patch accepted.\n+\n+The general cycle for patch review and acceptance is:\n+\n+#. Submit the patch.\n+\n+#. Check the automatic test reports in the coming hours.\n+\n+#. Wait for review comments. While you are waiting review some other patches.\n+\n+#. Fix the review comments and submit a ``v n+1`` patchset::\n+\n+      git format-patch -3 -o --subject-prefix 'PATCH v2'\n+\n+#. Update Patchwork to mark your previous patches as \"Superseded\".\n+\n+#. If the patch is deemed suitable for merging by the relevant maintainer(s) or other developers they will ``ack``\n+   the patch with an email that includes something like::\n+\n+      Acked-by: Alex Smith <alex.smith@example.com>\n+\n+   **Note**: When acking patches please remove as much of the text of the patch email as possible.\n+   It is generally best to delete everything after the ``Signed-off-by:`` line.\n+\n+#. Having the patch ``Reviewed-by:`` and/or ``Tested-by:`` will also help the patch to be accepted.\n+\n+#. If the patch isn't deemed suitable based on being out of scope or conflicting with existing functionality\n+   it may receive a ``nack``.\n+   In this case you will need to make a more convincing technical argument in favor of your patches.\n+\n+#. In addition a patch will not be accepted if it doesn't address comments from a previous version with fixes or\n+   valid arguments.\n+\n+#. Acked patches will be merged in the current or next merge window.\n",
    "prefixes": [
        "dpdk-dev",
        "v2"
    ]
}