3 Contributing Code to DPDK
4 =========================
6 This document outlines the guidelines for submitting code to DPDK.
8 The DPDK development process is modelled (loosely) on the Linux Kernel development model so it is worth reading the
9 Linux kernel guide on submitting patches:
10 `How to Get Your Change Into the Linux Kernel <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_.
11 The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines.
14 The DPDK Development Process
15 -----------------------------
17 The DPDK development process has the following features:
19 * The code is hosted in a public git repository.
20 * There is a mailing list where developers submit patches.
21 * There are maintainers for hierarchical components.
22 * Patches are reviewed publicly on the mailing list.
23 * Successfully reviewed patches are merged to the repository.
27 * There are main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
28 * A patch should be sent for its target repository. Like net drivers should be on top of dpdk-next-net repository.
29 * All sub-repositories are merged into main repository for -rc1 and -rc2 versions of the release.
30 * After -rc2 release all patches should target main repository.
32 The mailing list for DPDK development is `dev@dpdk.org <http://dpdk.org/ml/archives/dev/>`_.
33 Contributors will need to `register for the mailing list <http://dpdk.org/ml/listinfo/dev>`_ in order to submit patches.
34 It is also worth registering for the DPDK `Patchwork <http://dpdk.org/dev/patchwork/project/dpdk/list/>`_
36 The development process requires some familiarity with the ``git`` version control system.
37 Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information.
40 Getting the Source Code
41 -----------------------
43 The source code can be cloned using either of the following:
47 git clone git://dpdk.org/dpdk
48 git clone http://dpdk.org/git/dpdk
50 sub-repositories (`list <http://dpdk.org/browse/next>`_)::
52 git clone git://dpdk.org/next/dpdk-next-*
53 git clone http://dpdk.org/git/next/dpdk-next-*
58 Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines and requirements:
60 * Follow the :ref:`coding_style` guidelines.
62 * If you add new files or directories you should add your name to the ``MAINTAINERS`` file.
64 * New external functions should be added to the local ``version.map`` file.
65 See the :doc:`Guidelines for ABI policy and versioning </contributing/versioning>`.
66 New external functions should also be added in alphabetical order.
68 * Important changes will require an addition to the release notes in ``doc/guides/rel_notes/``.
69 See the :ref:`Release Notes section of the Documentation Guidelines <doc_guidelines>` for details.
71 * Test the compilation works with different targets, compilers and options, see :ref:`contrib_check_compilation`.
73 * Don't break compilation between commits with forward dependencies in a patchset.
74 Each commit should compile on its own to allow for ``git bisect`` and continuous integration testing.
76 * Add tests to the the ``app/test`` unit test framework where possible.
78 * Add documentation, if relevant, in the form of Doxygen comments or a User Guide in RST format.
79 See the :ref:`Documentation Guidelines <doc_guidelines>`.
81 Once the changes have been made you should commit them to your local repo.
83 For small changes, that do not require specific explanations, it is better to keep things together in the
85 Larger changes that require different explanations should be separated into logical patches in a patchset.
86 A good way of thinking about whether a patch should be split is to consider whether the change could be
87 applied without dependencies as a backport.
89 As a guide to how patches should be structured run ``git log`` on similar files.
92 Commit Messages: Subject Line
93 -----------------------------
95 The first, summary, line of the git commit message becomes the subject line of the patch email.
96 Here are some guidelines for the summary line:
98 * The summary line must capture the area and the impact of the change.
100 * The summary line should be around 50 characters.
102 * The summary line should be lowercase apart from acronyms.
104 * It should be prefixed with the component name (use git log to check existing components).
107 ixgbe: fix offload config option name
109 config: increase max queues per port
111 * Use the imperative of the verb (like instructions to the code base).
113 * Don't add a period/full stop to the subject line or you will end up two in the patch name: ``dpdk_description..patch``.
115 The actual email subject line should be prefixed by ``[PATCH]`` and the version, if greater than v1,
116 for example: ``PATCH v2``.
117 The is generally added by ``git send-email`` or ``git format-patch``, see below.
119 If you are submitting an RFC draft of a feature you can use ``[RFC]`` instead of ``[PATCH]``.
120 An RFC patch doesn't have to be complete.
121 It is intended as a way of getting early feedback.
124 Commit Messages: Body
125 ---------------------
127 Here are some guidelines for the body of a commit message:
129 * The body of the message should describe the issue being fixed or the feature being added.
130 It is important to provide enough information to allow a reviewer to understand the purpose of the patch.
132 * When the change is obvious the body can be blank, apart from the signoff.
134 * The commit message must end with a ``Signed-off-by:`` line which is added using::
136 git commit --signoff # or -s
138 The purpose of the signoff is explained in the
139 `Developer's Certificate of Origin <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_
140 section of the Linux kernel guidelines.
144 All developers must ensure that they have read and understood the
145 Developer's Certificate of Origin section of the documentation prior
146 to applying the signoff and submitting a patch.
148 * The signoff must be a real name and not an alias or nickname.
149 More than one signoff is allowed.
151 * The text of the commit message should be wrapped at 72 characters.
153 * When fixing a regression, it is a good idea to reference the id of the commit which introduced the bug.
154 You can generate the required text using the following git alias::
156 git config alias.fixline "log -1 --abbrev=12 --format='Fixes: %h (\"%s\")'"
158 The ``Fixes:`` line can then be added to the commit message::
160 doc: fix vhost sample parameter
162 Update the docs to reflect removed dev-index.
164 Fixes: 17b8320a3e11 ("vhost: remove index parameter")
166 Signed-off-by: Alex Smith <alex.smith@example.com>
168 * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
170 * Use correct capitalization, punctuation and spelling.
172 In addition to the ``Signed-off-by:`` name the commit messages can also have one or more of the following:
174 * ``Reported-by:`` The reporter of the issue.
175 * ``Tested-by:`` The tester of the change.
176 * ``Reviewed-by:`` The reviewer of the change.
177 * ``Suggested-by:`` The person who suggested the change.
178 * ``Acked-by:`` When a previous version of the patch was acked and the ack is still relevant.
184 It is possible to send patches directly from git but for new contributors it is recommended to generate the
185 patches with ``git format-patch`` and then when everything looks okay, and the patches have been checked, to
186 send them with ``git send-email``.
188 Here are some examples of using ``git format-patch`` to generate patches:
190 .. code-block:: console
192 # Generate a patch from the last commit.
195 # Generate a patch from the last 3 commits.
198 # Generate the patches in a directory.
199 git format-patch -3 -o ~/patch/
201 # Add a cover letter to explain a patchset.
202 git format-patch -3 -o ~/patch/ --cover-letter
204 # Add a prefix with a version number.
205 git format-patch -3 -o ~/patch/ -v 2
208 Cover letters are useful for explaining a patchset and help to generate a logical threading to the patches.
209 Smaller notes can be put inline in the patch after the ``---`` separator, for example::
211 Subject: [PATCH] fm10k/base: add FM10420 device ids
213 Add the device ID for Boulder Rapids and Atwood Channel to enable
214 drivers to support those devices.
216 Signed-off-by: Alex Smith <alex.smith@example.com>
221 drivers/net/fm10k/base/fm10k_api.c | 6 ++++++
222 drivers/net/fm10k/base/fm10k_type.h | 6 ++++++
223 2 files changed, 12 insertions(+)
226 Version 2 and later of a patchset should also include a short log of the changes so the reviewer knows what has changed.
227 This can be added to the cover letter or the annotations.
232 * Fixed issued with version.map.
235 * Added i40e support.
236 * Renamed ethdev functions from rte_eth_ieee15888_*() to rte_eth_timesync_*()
237 since 802.1AS can be supported through the same interfaces.
240 .. _contrib_checkpatch:
245 Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``scripts``
246 directory of the DPDK repo.
247 This uses the Linux kernel development tool ``checkpatch.pl`` which can be obtained by cloning, and periodically,
248 updating the Linux kernel sources.
250 The path to the original Linux script must be set in the environment variable ``DPDK_CHECKPATCH_PATH``.
251 This, and any other configuration variables required by the development tools, are loaded from the following
252 files, in order of preference::
255 ~/.config/dpdk/devel.config
256 /etc/dpdk/devel.config.
258 Once the environment variable the script can be run as follows::
260 scripts/checkpatches.sh ~/patch/
262 The script usage is::
264 checkpatches.sh [-h] [-q] [-v] [patch1 [patch2] ...]]"
268 * ``-h``: help, usage.
269 * ``-q``: quiet. Don't output anything for files without issues.
271 * ``patchX``: path to one or more patches.
273 Then the git logs should be checked using the ``check-git-log.sh`` script.
275 The script usage is::
277 check-git-log.sh [range]
279 Where the range is a ``git log`` option.
282 .. _contrib_check_compilation:
287 Compilation of patches and changes should be tested using the the ``test-build.sh`` script in the ``scripts``
288 directory of the DPDK repo::
290 scripts/test-build.sh x86_64-native-linuxapp-gcc+next+shared
292 The script usage is::
294 test-build.sh [-h] [-jX] [-s] [config1 [config2] ...]]
298 * ``-h``: help, usage.
299 * ``-jX``: use X parallel jobs in "make".
300 * ``-s``: short test with only first config and without examples/doc.
301 * ``config``: default config name plus config switches delimited with a ``+`` sign.
303 Examples of configs are::
305 x86_64-native-linuxapp-gcc
306 x86_64-native-linuxapp-gcc+next+shared
307 x86_64-native-linuxapp-clang+shared
309 The builds can be modifies via the following environmental variables:
311 * ``DPDK_BUILD_TEST_CONFIGS`` (target1+option1+option2 target2)
312 * ``DPDK_DEP_CFLAGS``
313 * ``DPDK_DEP_LDFLAGS``
314 * ``DPDK_DEP_MOFED`` (y/[n])
315 * ``DPDK_DEP_PCAP`` (y/[n])
316 * ``DPDK_NOTIFY`` (notify-send)
318 These can be set from the command line or in the config files shown above in the :ref:`contrib_checkpatch`.
320 The recommended configurations and options to test compilation prior to submitting patches are::
322 x86_64-native-linuxapp-gcc+shared+next
323 x86_64-native-linuxapp-clang+shared
324 i686-native-linuxapp-gcc
326 export DPDK_DEP_ZLIB=y
327 export DPDK_DEP_PCAP=y
328 export DPDK_DEP_SSL=y
334 Patches should be sent to the mailing list using ``git send-email``.
335 You can configure an external SMTP with something like the following::
338 smtpuser = name@domain.com
339 smtpserver = smtp.domain.com
343 See the `Git send-email <https://git-scm.com/docs/git-send-email>`_ documentation for more details.
345 The patches should be sent to ``dev@dpdk.org``.
346 If the patches are a change to existing files then you should send them TO the maintainer(s) and CC ``dev@dpdk.org``.
347 The appropriate maintainer can be found in the ``MAINTAINERS`` file::
349 git send-email --to maintainer@some.org --cc dev@dpdk.org 000*.patch
351 New additions can be sent without a maintainer::
353 git send-email --to dev@dpdk.org 000*.patch
355 You can test the emails by sending it to yourself or with the ``--dry-run`` option.
357 If the patch is in relation to a previous email thread you can add it to the same thread using the Message ID::
359 git send-email --to dev@dpdk.org --in-reply-to <1234-foo@bar.com> 000*.patch
361 The Message ID can be found in the raw text of emails or at the top of each Patchwork patch,
362 `for example <http://dpdk.org/dev/patchwork/patch/7646/>`_.
363 Shallow threading (``--thread --no-chain-reply-to``) is preferred for a patch series.
365 Once submitted your patches will appear on the mailing list and in Patchwork.
367 Experienced committers may send patches directly with ``git send-email`` without the ``git format-patch`` step.
368 The options ``--annotate`` and ``confirm = always`` are recommended for checking patches before sending.
374 The more work you put into the previous steps the easier it will be to get a patch accepted.
376 The general cycle for patch review and acceptance is:
380 #. Check the automatic test reports in the coming hours.
382 #. Wait for review comments. While you are waiting review some other patches.
384 #. Fix the review comments and submit a ``v n+1`` patchset::
386 git format-patch -3 -v 2
388 #. Update Patchwork to mark your previous patches as "Superseded".
390 #. If the patch is deemed suitable for merging by the relevant maintainer(s) or other developers they will ``ack``
391 the patch with an email that includes something like::
393 Acked-by: Alex Smith <alex.smith@example.com>
395 **Note**: When acking patches please remove as much of the text of the patch email as possible.
396 It is generally best to delete everything after the ``Signed-off-by:`` line.
398 #. Having the patch ``Reviewed-by:`` and/or ``Tested-by:`` will also help the patch to be accepted.
400 #. If the patch isn't deemed suitable based on being out of scope or conflicting with existing functionality
401 it may receive a ``nack``.
402 In this case you will need to make a more convincing technical argument in favor of your patches.
404 #. In addition a patch will not be accepted if it doesn't address comments from a previous version with fixes or
407 #. Acked patches will be merged in the current or next merge window.