1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright 2018 The DPDK contributors
6 Contributing Code to DPDK
7 =========================
9 This document outlines the guidelines for submitting code to DPDK.
11 The DPDK development process is modelled (loosely) on the Linux Kernel development model so it is worth reading the
12 Linux kernel guide on submitting patches:
13 `How to Get Your Change Into the Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_.
14 The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines.
17 The DPDK Development Process
18 ----------------------------
20 The DPDK development process has the following features:
22 * The code is hosted in a public git repository.
23 * There is a mailing list where developers submit patches.
24 * There are maintainers for hierarchical components.
25 * Patches are reviewed publicly on the mailing list.
26 * Successfully reviewed patches are merged to the repository.
27 * Patches should be sent to the target repository or sub-tree, see below.
28 * All sub-repositories are merged into main repository for ``-rc1`` and ``-rc2`` versions of the release.
29 * After the ``-rc2`` release all patches should target the main repository.
31 The mailing list for DPDK development is `dev@dpdk.org <http://mails.dpdk.org/archives/dev/>`_.
32 Contributors will need to `register for the mailing list <http://mails.dpdk.org/listinfo/dev>`_ in order to submit patches.
33 It is also worth registering for the DPDK `Patchwork <http://patches.dpdk.org/project/dpdk/list/>`_
35 The development process requires some familiarity with the ``git`` version control system.
36 Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information.
41 The DPDK uses the Open Source BSD-3-Clause license for the core libraries and
42 drivers. The kernel components are GPL-2.0 licensed. DPDK uses single line
43 reference to Unique License Identifiers in source files as defined by the Linux
44 Foundation's `SPDX project <http://spdx.org/>`_.
46 DPDK uses first line of the file to be SPDX tag. In case of *#!* scripts, SPDX
47 tag can be placed in 2nd line of the file.
49 For example, to label a file as subject to the BSD-3-Clause license,
50 the following text would be used:
52 ``SPDX-License-Identifier: BSD-3-Clause``
54 To label a file as dual-licensed with BSD-3-Clause and GPL-2.0 (e.g., for code
55 that is shared between the kernel and userspace), the following text would be
58 ``SPDX-License-Identifier: (BSD-3-Clause OR GPL-2.0)``
60 Refer to ``licenses/README`` for more details.
62 Maintainers and Sub-trees
63 -------------------------
65 The DPDK maintenance hierarchy is divided into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
67 There are maintainers for the trees and for components within the tree.
69 Trees and maintainers are listed in the ``MAINTAINERS`` file. For example::
73 M: Some Name <some.name@email.com>
74 B: Another Name <another.name@email.com>
75 T: git://dpdk.org/next/dpdk-next-crypto
78 M: Some One <some.one@email.com>
79 F: drivers/crypto/aesni_gcm/
80 F: doc/guides/cryptodevs/aesni_gcm.rst
84 * ``M`` is a tree or component maintainer.
85 * ``B`` is a tree backup maintainer.
86 * ``T`` is a repository tree.
87 * ``F`` is a maintained file or directory.
89 Additional details are given in the ``MAINTAINERS`` file.
91 The role of the component maintainers is to:
93 * Review patches for the component or delegate the review.
94 The review should be done, ideally, within 1 week of submission to the mailing list.
95 * Add an ``acked-by`` to patches, or patchsets, that are ready for committing to a tree.
96 * Reply to questions asked about the component.
98 Component maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
99 Maintainers should have demonstrated a reasonable level of contributions or reviews to the component area.
100 The maintainer should be confirmed by an ``ack`` from an established contributor.
101 There can be more than one component maintainer if desired.
103 The role of the tree maintainers is to:
105 * Maintain the overall quality of their tree.
106 This can entail additional review, compilation checks or other tests deemed necessary by the maintainer.
107 * Commit patches that have been reviewed by component maintainers and/or other contributors.
108 The tree maintainer should determine if patches have been reviewed sufficiently.
109 * Ensure that patches are reviewed in a timely manner.
110 * Prepare the tree for integration.
111 * Ensure that there is a designated back-up maintainer and coordinate a handover for periods where the
112 tree maintainer can't perform their role.
114 Tree maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
115 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.
116 The maintainer should be confirmed by an ``ack`` from an existing tree maintainer.
117 Disagreements on trees or maintainers can be brought to the Technical Board.
119 The backup maintainer for the master tree should be selected from the existing sub-tree maintainers from the project.
120 The backup maintainer for a sub-tree should be selected from among the component maintainers within that sub-tree.
123 Getting the Source Code
124 -----------------------
126 The source code can be cloned using either of the following:
130 git clone git://dpdk.org/dpdk
131 git clone http://dpdk.org/git/dpdk
133 sub-repositories (`list <http://git.dpdk.org/next>`_)::
135 git clone git://dpdk.org/next/dpdk-next-*
136 git clone http://dpdk.org/git/next/dpdk-next-*
141 Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines and requirements:
143 * Follow the :ref:`coding_style` guidelines.
145 * If you add new files or directories you should add your name to the ``MAINTAINERS`` file.
147 * New external functions should be added to the local ``version.map`` file.
148 See the :doc:`Guidelines for ABI policy and versioning </contributing/versioning>`.
149 New external functions should also be added in alphabetical order.
151 * Important changes will require an addition to the release notes in ``doc/guides/rel_notes/``.
152 See the :ref:`Release Notes section of the Documentation Guidelines <doc_guidelines>` for details.
154 * Test the compilation works with different targets, compilers and options, see :ref:`contrib_check_compilation`.
156 * Don't break compilation between commits with forward dependencies in a patchset.
157 Each commit should compile on its own to allow for ``git bisect`` and continuous integration testing.
159 * Add tests to the ``app/test`` unit test framework where possible.
161 * Add documentation, if relevant, in the form of Doxygen comments or a User Guide in RST format.
162 See the :ref:`Documentation Guidelines <doc_guidelines>`.
164 Once the changes have been made you should commit them to your local repo.
166 For small changes, that do not require specific explanations, it is better to keep things together in the
168 Larger changes that require different explanations should be separated into logical patches in a patchset.
169 A good way of thinking about whether a patch should be split is to consider whether the change could be
170 applied without dependencies as a backport.
172 It is better to keep the related documentation changes in the same patch
173 file as the code, rather than one big documentation patch at then end of a
174 patchset. This makes it easier for future maintenance and development of the
177 As a guide to how patches should be structured run ``git log`` on similar files.
180 Commit Messages: Subject Line
181 -----------------------------
183 The first, summary, line of the git commit message becomes the subject line of the patch email.
184 Here are some guidelines for the summary line:
186 * The summary line must capture the area and the impact of the change.
188 * The summary line should be around 50 characters.
190 * The summary line should be lowercase apart from acronyms.
192 * It should be prefixed with the component name (use git log to check existing components).
195 ixgbe: fix offload config option name
197 config: increase max queues per port
199 * Use the imperative of the verb (like instructions to the code base).
201 * Don't add a period/full stop to the subject line or you will end up two in the patch name: ``dpdk_description..patch``.
203 The actual email subject line should be prefixed by ``[PATCH]`` and the version, if greater than v1,
204 for example: ``PATCH v2``.
205 The is generally added by ``git send-email`` or ``git format-patch``, see below.
207 If you are submitting an RFC draft of a feature you can use ``[RFC]`` instead of ``[PATCH]``.
208 An RFC patch doesn't have to be complete.
209 It is intended as a way of getting early feedback.
212 Commit Messages: Body
213 ---------------------
215 Here are some guidelines for the body of a commit message:
217 * The body of the message should describe the issue being fixed or the feature being added.
218 It is important to provide enough information to allow a reviewer to understand the purpose of the patch.
220 * When the change is obvious the body can be blank, apart from the signoff.
222 * The commit message must end with a ``Signed-off-by:`` line which is added using::
224 git commit --signoff # or -s
226 The purpose of the signoff is explained in the
227 `Developer's Certificate of Origin <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1>`_
228 section of the Linux kernel guidelines.
232 All developers must ensure that they have read and understood the
233 Developer's Certificate of Origin section of the documentation prior
234 to applying the signoff and submitting a patch.
236 * The signoff must be a real name and not an alias or nickname.
237 More than one signoff is allowed.
239 * The text of the commit message should be wrapped at 72 characters.
241 * When fixing a regression, it is required to reference the id of the commit
242 which introduced the bug, and put the original author of that commit on CC.
243 You can generate the required lines using the following git alias, which prints
244 the commit SHA and the author of the original code::
246 git config alias.fixline "log -1 --abbrev=12 --format='Fixes: %h (\"%s\")%nCc: %ae'"
248 The output of ``git fixline <SHA>`` must then be added to the commit message::
250 doc: fix some parameter description
252 Update the docs, fixing description of some parameter.
254 Fixes: abcdefgh1234 ("doc: add some parameter")
255 Cc: author@example.com
257 Signed-off-by: Alex Smith <alex.smith@example.com>
259 * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
261 * Use correct capitalization, punctuation and spelling.
263 In addition to the ``Signed-off-by:`` name the commit messages can also have
264 tags for who reported, suggested, tested and reviewed the patch being
265 posted. Please refer to the `Tested, Acked and Reviewed by`_ section.
267 Patch Fix Related Issues
268 ~~~~~~~~~~~~~~~~~~~~~~~~
270 `Coverity <https://scan.coverity.com/projects/dpdk-data-plane-development-kit>`_
271 is a tool for static code analysis.
272 It is used as a cloud-based service used to scan the DPDK source code,
273 and alert developers of any potential defects in the source code.
274 When fixing an issue found by Coverity, the patch must contain a Coverity issue ID
275 in the body of the commit message. For example::
278 doc: fix some parameter description
280 Update the docs, fixing description of some parameter.
282 Coverity issue: 12345
283 Fixes: abcdefgh1234 ("doc: add some parameter")
284 Cc: author@example.com
286 Signed-off-by: Alex Smith <alex.smith@example.com>
289 `Bugzilla <https://bugs.dpdk.org>`_
290 is a bug- or issue-tracking system.
291 Bug-tracking systems allow individual or groups of developers
292 effectively to keep track of outstanding problems with their product.
293 When fixing an issue raised in Bugzilla, the patch must contain
294 a Bugzilla issue ID in the body of the commit message.
297 doc: fix some parameter description
299 Update the docs, fixing description of some parameter.
302 Fixes: abcdefgh1234 ("doc: add some parameter")
303 Cc: author@example.com
305 Signed-off-by: Alex Smith <alex.smith@example.com>
307 Patch for Stable Releases
308 ~~~~~~~~~~~~~~~~~~~~~~~~~
310 All fix patches to the master branch that are candidates for backporting
311 should also be CCed to the `stable@dpdk.org <http://mails.dpdk.org/listinfo/stable>`_
313 In the commit message body the Cc: stable@dpdk.org should be inserted as follows::
315 doc: fix some parameter description
317 Update the docs, fixing description of some parameter.
319 Fixes: abcdefgh1234 ("doc: add some parameter")
322 Signed-off-by: Alex Smith <alex.smith@example.com>
324 For further information on stable contribution you can go to
325 :doc:`Stable Contribution Guide <stable>`.
331 It is possible to send patches directly from git but for new contributors it is recommended to generate the
332 patches with ``git format-patch`` and then when everything looks okay, and the patches have been checked, to
333 send them with ``git send-email``.
335 Here are some examples of using ``git format-patch`` to generate patches:
337 .. code-block:: console
339 # Generate a patch from the last commit.
342 # Generate a patch from the last 3 commits.
345 # Generate the patches in a directory.
346 git format-patch -3 -o ~/patch/
348 # Add a cover letter to explain a patchset.
349 git format-patch -3 -o ~/patch/ --cover-letter
351 # Add a prefix with a version number.
352 git format-patch -3 -o ~/patch/ -v 2
355 Cover letters are useful for explaining a patchset and help to generate a logical threading to the patches.
356 Smaller notes can be put inline in the patch after the ``---`` separator, for example::
358 Subject: [PATCH] fm10k/base: add FM10420 device ids
360 Add the device ID for Boulder Rapids and Atwood Channel to enable
361 drivers to support those devices.
363 Signed-off-by: Alex Smith <alex.smith@example.com>
368 drivers/net/fm10k/base/fm10k_api.c | 6 ++++++
369 drivers/net/fm10k/base/fm10k_type.h | 6 ++++++
370 2 files changed, 12 insertions(+)
373 Version 2 and later of a patchset should also include a short log of the changes so the reviewer knows what has changed.
374 This can be added to the cover letter or the annotations.
379 * Fixed issued with version.map.
382 * Added i40e support.
383 * Renamed ethdev functions from rte_eth_ieee15888_*() to rte_eth_timesync_*()
384 since 802.1AS can be supported through the same interfaces.
387 .. _contrib_checkpatch:
392 Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``devtools``
393 directory of the DPDK repo.
394 This uses the Linux kernel development tool ``checkpatch.pl`` which can be obtained by cloning, and periodically,
395 updating the Linux kernel sources.
397 The path to the original Linux script must be set in the environment variable ``DPDK_CHECKPATCH_PATH``.
398 This, and any other configuration variables required by the development tools, are loaded from the following
399 files, in order of preference::
402 ~/.config/dpdk/devel.config
403 /etc/dpdk/devel.config.
405 Once the environment variable the script can be run as follows::
407 devtools/checkpatches.sh ~/patch/
409 The script usage is::
411 checkpatches.sh [-h] [-q] [-v] [patch1 [patch2] ...]]"
415 * ``-h``: help, usage.
416 * ``-q``: quiet. Don't output anything for files without issues.
418 * ``patchX``: path to one or more patches.
420 Then the git logs should be checked using the ``check-git-log.sh`` script.
422 The script usage is::
424 check-git-log.sh [range]
426 Where the range is a ``git log`` option.
429 .. _contrib_check_compilation:
434 Compilation of patches and changes should be tested using the ``test-build.sh`` script in the ``devtools``
435 directory of the DPDK repo::
437 devtools/test-build.sh x86_64-native-linuxapp-gcc+next+shared
439 The script usage is::
441 test-build.sh [-h] [-jX] [-s] [config1 [config2] ...]]
445 * ``-h``: help, usage.
446 * ``-jX``: use X parallel jobs in "make".
447 * ``-s``: short test with only first config and without examples/doc.
448 * ``config``: default config name plus config switches delimited with a ``+`` sign.
450 Examples of configs are::
452 x86_64-native-linuxapp-gcc
453 x86_64-native-linuxapp-gcc+next+shared
454 x86_64-native-linuxapp-clang+shared
456 The builds can be modified via the following environmental variables:
458 * ``DPDK_BUILD_TEST_CONFIGS`` (target1+option1+option2 target2)
459 * ``DPDK_DEP_CFLAGS``
460 * ``DPDK_DEP_LDFLAGS``
461 * ``DPDK_DEP_PCAP`` (y/[n])
462 * ``DPDK_NOTIFY`` (notify-send)
464 These can be set from the command line or in the config files shown above in the :ref:`contrib_checkpatch`.
466 The recommended configurations and options to test compilation prior to submitting patches are::
468 x86_64-native-linuxapp-gcc+shared+next
469 x86_64-native-linuxapp-clang+shared
470 i686-native-linuxapp-gcc
472 export DPDK_DEP_ZLIB=y
473 export DPDK_DEP_PCAP=y
474 export DPDK_DEP_SSL=y
480 Patches should be sent to the mailing list using ``git send-email``.
481 You can configure an external SMTP with something like the following::
484 smtpuser = name@domain.com
485 smtpserver = smtp.domain.com
489 See the `Git send-email <https://git-scm.com/docs/git-send-email>`_ documentation for more details.
491 The patches should be sent to ``dev@dpdk.org``.
492 If the patches are a change to existing files then you should send them TO the maintainer(s) and CC ``dev@dpdk.org``.
493 The appropriate maintainer can be found in the ``MAINTAINERS`` file::
495 git send-email --to maintainer@some.org --cc dev@dpdk.org 000*.patch
497 Script ``get-maintainer.sh`` can be used to select maintainers automatically::
499 git send-email --to-cmd ./devtools/get-maintainer.sh --cc dev@dpdk.org 000*.patch
501 New additions can be sent without a maintainer::
503 git send-email --to dev@dpdk.org 000*.patch
505 You can test the emails by sending it to yourself or with the ``--dry-run`` option.
507 If the patch is in relation to a previous email thread you can add it to the same thread using the Message ID::
509 git send-email --to dev@dpdk.org --in-reply-to <1234-foo@bar.com> 000*.patch
511 The Message ID can be found in the raw text of emails or at the top of each Patchwork patch,
512 `for example <http://patches.dpdk.org/patch/7646/>`_.
513 Shallow threading (``--thread --no-chain-reply-to``) is preferred for a patch series.
515 Once submitted your patches will appear on the mailing list and in Patchwork.
517 Experienced committers may send patches directly with ``git send-email`` without the ``git format-patch`` step.
518 The options ``--annotate`` and ``confirm = always`` are recommended for checking patches before sending.
521 Backporting patches for Stable Releases
522 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
524 Sometimes a maintainer or contributor wishes, or can be asked, to send a patch
525 for a stable release rather than mainline.
526 In this case the patch(es) should be sent to ``stable@dpdk.org``,
527 not to ``dev@dpdk.org``.
529 Given that there are multiple stable releases being maintained at the same time,
530 please specify exactly which branch(es) the patch is for
531 using ``git send-email --subject-prefix='PATCH 16.11' ...``
532 and also optionally in the cover letter or in the annotation.
538 Patches are reviewed by the community, relying on the experience and
539 collaboration of the members to double-check each other's work. There are a
540 number of ways to indicate that you have checked a patch on the mailing list.
543 Tested, Acked and Reviewed by
544 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
546 To indicate that you have interacted with a patch on the mailing list you
547 should respond to the patch in an email with one of the following tags:
555 The tag should be on a separate line as follows::
557 tag-here: Name Surname <email@address.com>
559 Each of these tags has a specific meaning. In general, the DPDK community
560 follows the kernel usage of the tags. A short summary of the meanings of each
561 tag is given here for reference:
563 .. _statement: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight
565 ``Reviewed-by:`` is a strong statement_ that the patch is an appropriate state
566 for merging without any remaining serious technical issues. Reviews from
567 community members who are known to understand the subject area and to perform
568 thorough reviews will increase the likelihood of the patch getting merged.
570 ``Acked-by:`` is a record that the person named was not directly involved in
571 the preparation of the patch but wishes to signify and record their acceptance
574 ``Tested-by:`` indicates that the patch has been successfully tested (in some
575 environment) by the person named.
577 ``Reported-by:`` is used to acknowledge person who found or reported the bug.
579 ``Suggested-by:`` indicates that the patch idea was suggested by the named
584 Steps to getting your patch merged
585 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
587 The more work you put into the previous steps the easier it will be to get a
588 patch accepted. The general cycle for patch review and acceptance is:
592 #. Check the automatic test reports in the coming hours.
594 #. Wait for review comments. While you are waiting review some other patches.
596 #. Fix the review comments and submit a ``v n+1`` patchset::
598 git format-patch -3 -v 2
600 #. Update Patchwork to mark your previous patches as "Superseded".
602 #. If the patch is deemed suitable for merging by the relevant maintainer(s) or other developers they will ``ack``
603 the patch with an email that includes something like::
605 Acked-by: Alex Smith <alex.smith@example.com>
607 **Note**: When acking patches please remove as much of the text of the patch email as possible.
608 It is generally best to delete everything after the ``Signed-off-by:`` line.
610 #. Having the patch ``Reviewed-by:`` and/or ``Tested-by:`` will also help the patch to be accepted.
612 #. If the patch isn't deemed suitable based on being out of scope or conflicting with existing functionality
613 it may receive a ``nack``.
614 In this case you will need to make a more convincing technical argument in favor of your patches.
616 #. In addition a patch will not be accepted if it doesn't address comments from a previous version with fixes or
619 #. It is the responsibility of a maintainer to ensure that patches are reviewed and to provide an ``ack`` or
620 ``nack`` of those patches as appropriate.
622 #. Once a patch has been acked by the relevant maintainer, reviewers may still comment on it for a further
623 two weeks. After that time, the patch should be merged into the relevant git tree for the next release.
624 Additional notes and restrictions:
626 * Patches should be acked by a maintainer at least two days before the release merge
627 deadline, in order to make that release.
628 * For patches acked with less than two weeks to go to the merge deadline, all additional
629 comments should be made no later than two days before the merge deadline.
630 * After the appropriate time for additional feedback has passed, if the patch has not yet
631 been merged to the relevant tree by the committer, it should be treated as though it had,
632 in that any additional changes needed to it must be addressed by a follow-on patch, rather
633 than rework of the original.
634 * Trivial patches may be merged sooner than described above at the tree committer's
640 The following are the DPDK maintainers as listed in the ``MAINTAINERS`` file
641 in the DPDK root directory.
643 .. literalinclude:: ../../../MAINTAINERS