The DPDK development process is modelled (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.
The DPDK Development Process
------------------------------
+----------------------------
The DPDK development process has the following features:
* 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.
+* Successfully reviewed patches are merged to the repository.
+* Patches should be sent to the target repository or sub-tree, see below.
+* 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.
Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information.
+Maintainers and Sub-trees
+-------------------------
+
+The DPDK maintenance hierarchy is divided into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
+
+There are maintainers for the trees and for components within the tree.
+
+Trees and maintainers are listed in the ``MAINTAINERS`` file. For example::
+
+ Crypto Drivers
+ --------------
+ M: Some Name <some.name@email.com>
+ B: Another Name <another.name@email.com>
+ T: git://dpdk.org/next/dpdk-next-crypto
+
+ Intel AES-NI GCM PMD
+ M: Some One <some.one@email.com>
+ F: drivers/crypto/aesni_gcm/
+ F: doc/guides/cryptodevs/aesni_gcm.rst
+
+Where:
+
+* ``M`` is a tree or component maintainer.
+* ``B`` is a tree backup maintainer.
+* ``T`` is a repository tree.
+* ``F`` is a maintained file or directory.
+
+Additional details are given in the ``MAINTAINERS`` file.
+
+The role of the component maintainers is to:
+
+* 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.
+The maintainer should be confirmed by an ``ack`` from an established contributor.
+There can be more than one component maintainer if desired.
+
+The role of the tree maintainers is to:
+
+* Maintain the overall quality of their tree.
+ This can entail additional review, compilation checks or other tests deemed necessary by the maintainer.
+* Commit patches that have been reviewed by component maintainers and/or other contributors.
+ The tree maintainer should determine if patches have been reviewed sufficiently.
+* Ensure that patches are reviewed in a timely manner.
+* Prepare the tree for integration.
+* Ensure that there is a designated back-up maintainer and coordinate a handover for periods where the
+ tree maintainer can't perform their role.
+
+Tree maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
+The proposer should justify the need for a new sub-tree and should have demonstrated a sufficient level of contributions in the area or to a similar area.
+The maintainer should be confirmed by an ``ack`` from an existing tree maintainer.
+Disagreements on trees or maintainers can be brought to the Technical Board.
+
+The backup maintainer for the master tree should be selected from the existing sub-tree maintainers from the project.
+The backup maintainer for a sub-tree should be selected from among the component maintainers within that sub-tree.
+
+
Getting the Source Code
-----------------------
-The source code can be cloned using either of the following::
+The source code can be cloned using either of the following:
- git clone git://dpdk.org/dpdk
+main repository::
+ git clone git://dpdk.org/dpdk
git clone http://dpdk.org/git/dpdk
+sub-repositories (`list <http://dpdk.org/browse/next>`_)::
+
+ git clone git://dpdk.org/next/dpdk-next-*
+ git clone http://dpdk.org/git/next/dpdk-next-*
Make your Changes
-----------------
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::
* 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.
-* ``Acked-by:`` When a previous version of the patch was acked and the ack is still relevant.
+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.
Creating Patches
Checking the Patches
--------------------
-Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``scripts``
+Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``devtools``
directory of the DPDK repo.
This uses the Linux kernel development tool ``checkpatch.pl`` which can be obtained by cloning, and periodically,
updating the Linux kernel sources.
Once the environment variable the script can be run as follows::
- scripts/checkpatches.sh ~/patch/
+ devtools/checkpatches.sh ~/patch/
The script usage is::
Checking Compilation
--------------------
-Compilation of patches and changes should be tested using the the ``test-build.sh`` script in the ``scripts``
+Compilation of patches and changes should be tested using the the ``test-build.sh`` script in the ``devtools``
directory of the DPDK repo::
- scripts/test-build.sh x86_64-native-linuxapp-gcc+next+shared
+ devtools/test-build.sh x86_64-native-linuxapp-gcc+next+shared
The script usage is::
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 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 general cycle for patch review and acceptance is:
+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.
Code Review / deb_dpdk.git / blobdiff