+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright 2018 The DPDK contributors
+
.. submitting_patches:
Contributing Code to DPDK
This document outlines the guidelines for submitting code to DPDK.
-The DPDK development process is modelled (loosely) on the Linux Kernel development model so it is worth reading the
+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 <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_.
+`How to Get Your Change Into the Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_.
The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines.
* All sub-repositories are merged into main repository for ``-rc1`` and ``-rc2`` versions of the release.
* After the ``-rc2`` release all patches should target the main repository.
-The mailing list for DPDK development is `dev@dpdk.org <http://dpdk.org/ml/archives/dev/>`_.
-Contributors will need to `register for the mailing list <http://dpdk.org/ml/listinfo/dev>`_ in order to submit patches.
-It is also worth registering for the DPDK `Patchwork <http://dpdk.org/dev/patchwork/project/dpdk/list/>`_
+The mailing list for DPDK development is `dev@dpdk.org <http://mails.dpdk.org/archives/dev/>`_.
+Contributors will need to `register for the mailing list <http://mails.dpdk.org/listinfo/dev>`_ in order to submit patches.
+It is also worth registering for the DPDK `Patchwork <http://patches.dpdk.org/project/dpdk/list/>`_
+
+If you are using the GitHub service, you can link your repository to
+the ``travis-ci.org`` build service. When you push patches to your GitHub
+repository, the travis service will automatically build your changes.
The development process requires some familiarity with the ``git`` version control system.
Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information.
+Source License
+--------------
+
+The DPDK uses the Open Source BSD-3-Clause license for the core libraries and
+drivers. The kernel components are GPL-2.0 licensed. DPDK uses single line
+reference to Unique License Identifiers in source files as defined by the Linux
+Foundation's `SPDX project <http://spdx.org/>`_.
+
+DPDK uses first line of the file to be SPDX tag. In case of *#!* scripts, SPDX
+tag can be placed in 2nd line of the file.
+
+For example, to label a file as subject to the BSD-3-Clause license,
+the following text would be used:
+
+``SPDX-License-Identifier: BSD-3-Clause``
+
+To label a file as dual-licensed with BSD-3-Clause and GPL-2.0 (e.g., for code
+that is shared between the kernel and userspace), the following text would be
+used:
+
+``SPDX-License-Identifier: (BSD-3-Clause OR GPL-2.0)``
+
+Refer to ``licenses/README`` for more details.
Maintainers and Sub-trees
-------------------------
* Review patches for the component or delegate the review.
The review should be done, ideally, within 1 week of submission to the mailing list.
* Add an ``acked-by`` to patches, or patchsets, that are ready for committing to a tree.
+* Reply to questions asked about the component.
Component maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
Maintainers should have demonstrated a reasonable level of contributions or reviews to the component area.
git clone git://dpdk.org/dpdk
git clone http://dpdk.org/git/dpdk
-sub-repositories (`list <http://dpdk.org/browse/next>`_)::
+sub-repositories (`list <http://git.dpdk.org/next>`_)::
git clone git://dpdk.org/next/dpdk-next-*
git clone http://dpdk.org/git/next/dpdk-next-*
* Don't break compilation between commits with forward dependencies in a patchset.
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 tests to the ``app/test`` unit test framework where possible.
* Add documentation, if relevant, in the form of Doxygen comments or a User Guide in RST format.
See the :ref:`Documentation Guidelines <doc_guidelines>`.
A good way of thinking about whether a patch should be split is to consider whether the change could be
applied without dependencies as a backport.
+It is better to keep the related documentation changes in the same patch
+file as the code, rather than one big documentation patch at then end of a
+patchset. This makes it easier for future maintenance and development of the
+code.
+
As a guide to how patches should be structured run ``git log`` on similar files.
git commit --signoff # or -s
The purpose of the signoff is explained in the
- `Developer's Certificate of Origin <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_
+ `Developer's Certificate of Origin <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1>`_
section of the Linux kernel guidelines.
.. Note::
* 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 using the following git alias::
+* When fixing a regression, it is required to reference the id of the commit
+ which introduced the bug, and put the original author of that commit on CC.
+ You can generate the required lines using the following git alias, which prints
+ the commit SHA and the author of the original code::
- git config alias.fixline "log -1 --abbrev=12 --format='Fixes: %h (\"%s\")'"
+ git config alias.fixline "log -1 --abbrev=12 --format='Fixes: %h (\"%s\")%nCc: %ae'"
- The ``Fixes:`` line can then be added to the commit message::
+ The output of ``git fixline <SHA>`` must then be added to the commit message::
- doc: fix vhost sample parameter
+ doc: fix some parameter description
- Update the docs to reflect removed dev-index.
+ Update the docs, fixing description of some parameter.
- Fixes: 17b8320a3e11 ("vhost: remove index parameter")
+ Fixes: abcdefgh1234 ("doc: add some parameter")
+ Cc: author@example.com
Signed-off-by: Alex Smith <alex.smith@example.com>
* 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:
+In addition to the ``Signed-off-by:`` name the commit messages can also have
+tags for who reported, suggested, tested and reviewed the patch being
+posted. Please refer to the `Tested, Acked and Reviewed by`_ section.
+
+Patch Fix Related Issues
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Coverity <https://scan.coverity.com/projects/dpdk-data-plane-development-kit>`_
+is a tool for static code analysis.
+It is used as a cloud-based service used to scan the DPDK source code,
+and alert developers of any potential defects in the source code.
+When fixing an issue found by Coverity, the patch must contain a Coverity issue ID
+in the body of the commit message. For example::
+
+
+ doc: fix some parameter description
+
+ Update the docs, fixing description of some parameter.
+
+ Coverity issue: 12345
+ Fixes: abcdefgh1234 ("doc: add some parameter")
+ Cc: author@example.com
-* ``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.
-* ``Acked-by:`` When a previous version of the patch was acked and the ack is still relevant.
+ Signed-off-by: Alex Smith <alex.smith@example.com>
+
+
+`Bugzilla <https://bugs.dpdk.org>`_
+is a bug- or issue-tracking system.
+Bug-tracking systems allow individual or groups of developers
+effectively to keep track of outstanding problems with their product.
+When fixing an issue raised in Bugzilla, the patch must contain
+a Bugzilla issue ID in the body of the commit message.
+For example::
+
+ doc: fix some parameter description
+
+ Update the docs, fixing description of some parameter.
+
+ Bugzilla ID: 12345
+ Fixes: abcdefgh1234 ("doc: add some parameter")
+ Cc: author@example.com
+
+ Signed-off-by: Alex Smith <alex.smith@example.com>
+
+Patch for Stable Releases
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All fix patches to the master branch that are candidates for backporting
+should also be CCed to the `stable@dpdk.org <http://mails.dpdk.org/listinfo/stable>`_
+mailing list.
+In the commit message body the Cc: stable@dpdk.org should be inserted as follows::
+
+ doc: fix some parameter description
+
+ Update the docs, fixing description of some parameter.
+
+ Fixes: abcdefgh1234 ("doc: add some parameter")
+ Cc: stable@dpdk.org
+
+ Signed-off-by: Alex Smith <alex.smith@example.com>
+
+For further information on stable contribution you can go to
+:doc:`Stable Contribution Guide <stable>`.
Creating Patches
Checking Compilation
--------------------
-Compilation of patches and changes should be tested using the the ``test-build.sh`` script in the ``devtools``
+Makefile System
+~~~~~~~~~~~~~~~
+
+Compilation of patches and changes should be tested using the ``test-build.sh`` script in the ``devtools``
directory of the DPDK repo::
- devtools/test-build.sh x86_64-native-linuxapp-gcc+next+shared
+ devtools/test-build.sh x86_64-native-linux-gcc+next+shared
The script usage is::
Examples of configs are::
- x86_64-native-linuxapp-gcc
- x86_64-native-linuxapp-gcc+next+shared
- x86_64-native-linuxapp-clang+shared
+ x86_64-native-linux-gcc
+ x86_64-native-linux-gcc+next+shared
+ x86_64-native-linux-clang+shared
-The builds can be modifies via the following environmental variables:
+The builds can be modified via the following environmental variables:
* ``DPDK_BUILD_TEST_CONFIGS`` (target1+option1+option2 target2)
* ``DPDK_DEP_CFLAGS``
* ``DPDK_DEP_LDFLAGS``
-* ``DPDK_DEP_MOFED`` (y/[n])
* ``DPDK_DEP_PCAP`` (y/[n])
* ``DPDK_NOTIFY`` (notify-send)
The recommended configurations and options to test compilation prior to submitting patches are::
- x86_64-native-linuxapp-gcc+shared+next
- x86_64-native-linuxapp-clang+shared
- i686-native-linuxapp-gcc
+ x86_64-native-linux-gcc+shared+next
+ x86_64-native-linux-clang+shared
+ i686-native-linux-gcc
export DPDK_DEP_ZLIB=y
export DPDK_DEP_PCAP=y
export DPDK_DEP_SSL=y
+Meson System
+~~~~~~~~~~~~
+
+Compilation of patches is to be tested with ``devtools/test-meson-builds.sh`` script.
+
+The script internally checks for dependencies, then builds for several
+combinations of compilation configuration.
+
Sending Patches
---------------
git send-email --to maintainer@some.org --cc dev@dpdk.org 000*.patch
+Script ``get-maintainer.sh`` can be used to select maintainers automatically::
+
+ git send-email --to-cmd ./devtools/get-maintainer.sh --cc dev@dpdk.org 000*.patch
+
New additions can be sent without a maintainer::
git send-email --to dev@dpdk.org 000*.patch
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 <http://dpdk.org/dev/patchwork/patch/7646/>`_.
+`for example <http://patches.dpdk.org/patch/7646/>`_.
Shallow threading (``--thread --no-chain-reply-to``) is preferred for a patch series.
Once submitted your patches will appear on the mailing list and in Patchwork.
The options ``--annotate`` and ``confirm = always`` are recommended for checking patches before sending.
+Backporting patches for Stable Releases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes a maintainer or contributor wishes, or can be asked, to send a patch
+for a stable release rather than mainline.
+In this case the patch(es) should be sent to ``stable@dpdk.org``,
+not to ``dev@dpdk.org``.
+
+Given that there are multiple stable releases being maintained at the same time,
+please specify exactly which branch(es) the patch is for
+using ``git send-email --subject-prefix='PATCH 16.11' ...``
+and also optionally in the cover letter or in the annotation.
+
+
The Review Process
------------------
-The more work you put into the previous steps the easier it will be to get a patch accepted.
+Patches are reviewed by the community, relying on the experience and
+collaboration of the members to double-check each other's work. There are a
+number of ways to indicate that you have checked a patch on the mailing list.
+
+
+Tested, Acked and Reviewed by
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To indicate that you have interacted with a patch on the mailing list you
+should respond to the patch in an email with one of the following tags:
+
+ * Reviewed-by:
+ * Acked-by:
+ * Tested-by:
+ * Reported-by:
+ * Suggested-by:
-The general cycle for patch review and acceptance is:
+The tag should be on a separate line as follows::
+
+ tag-here: Name Surname <email@address.com>
+
+Each of these tags has a specific meaning. In general, the DPDK community
+follows the kernel usage of the tags. A short summary of the meanings of each
+tag is given here for reference:
+
+.. _statement: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight
+
+``Reviewed-by:`` is a strong statement_ that the patch is an appropriate state
+for merging without any remaining serious technical issues. Reviews from
+community members who are known to understand the subject area and to perform
+thorough reviews will increase the likelihood of the patch getting merged.
+
+``Acked-by:`` is a record that the person named was not directly involved in
+the preparation of the patch but wishes to signify and record their acceptance
+and approval of it.
+
+``Tested-by:`` indicates that the patch has been successfully tested (in some
+environment) by the person named.
+
+``Reported-by:`` is used to acknowledge person who found or reported the bug.
+
+``Suggested-by:`` indicates that the patch idea was suggested by the named
+person.
+
+
+
+Steps to getting your patch merged
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
#. In addition a patch will not be accepted if it doesn't address comments from a previous version with fixes or
valid arguments.
-#. Acked patches will be merged in the current or next merge window.
+#. It is the responsibility of a maintainer to ensure that patches are reviewed and to provide an ``ack`` or
+ ``nack`` of those patches as appropriate.
+
+#. Once a patch has been acked by the relevant maintainer, reviewers may still comment on it for a further
+ two weeks. After that time, the patch should be merged into the relevant git tree for the next release.
+ Additional notes and restrictions:
+
+ * Patches should be acked by a maintainer at least two days before the release merge
+ deadline, in order to make that release.
+ * For patches acked with less than two weeks to go to the merge deadline, all additional
+ comments should be made no later than two days before the merge deadline.
+ * After the appropriate time for additional feedback has passed, if the patch has not yet
+ been merged to the relevant tree by the committer, it should be treated as though it had,
+ in that any additional changes needed to it must be addressed by a follow-on patch, rather
+ than rework of the original.
+ * Trivial patches may be merged sooner than described above at the tree committer's
+ discretion.
+
+DPDK Maintainers
+----------------
+
+The following are the DPDK maintainers as listed in the ``MAINTAINERS`` file
+in the DPDK root directory.
+
+.. literalinclude:: ../../../MAINTAINERS
+ :lines: 3-
git.droids-corp.org / dpdk.git / blobdiff