]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright 2018 The DPDK contributors | |
3 | ||
7c673cae FG |
4 | .. submitting_patches: |
5 | ||
6 | Contributing Code to DPDK | |
7 | ========================= | |
8 | ||
9 | This document outlines the guidelines for submitting code to DPDK. | |
10 | ||
9f95a23c | 11 | The DPDK development process is modeled (loosely) on the Linux Kernel development model so it is worth reading the |
7c673cae | 12 | Linux kernel guide on submitting patches: |
11fdf7f2 | 13 | `How to Get Your Change Into the Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_. |
7c673cae FG |
14 | The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines. |
15 | ||
16 | ||
17 | The DPDK Development Process | |
11fdf7f2 | 18 | ---------------------------- |
7c673cae FG |
19 | |
20 | The DPDK development process has the following features: | |
21 | ||
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. | |
11fdf7f2 TL |
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. | |
7c673cae | 30 | |
9f95a23c TL |
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/>`_ | |
34 | ||
35 | If you are using the GitHub service, you can link your repository to | |
36 | the ``travis-ci.org`` build service. When you push patches to your GitHub | |
37 | repository, the travis service will automatically build your changes. | |
7c673cae FG |
38 | |
39 | The development process requires some familiarity with the ``git`` version control system. | |
40 | Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information. | |
41 | ||
11fdf7f2 TL |
42 | Source License |
43 | -------------- | |
44 | ||
45 | The DPDK uses the Open Source BSD-3-Clause license for the core libraries and | |
46 | drivers. The kernel components are GPL-2.0 licensed. DPDK uses single line | |
47 | reference to Unique License Identifiers in source files as defined by the Linux | |
48 | Foundation's `SPDX project <http://spdx.org/>`_. | |
49 | ||
50 | DPDK uses first line of the file to be SPDX tag. In case of *#!* scripts, SPDX | |
51 | tag can be placed in 2nd line of the file. | |
52 | ||
53 | For example, to label a file as subject to the BSD-3-Clause license, | |
54 | the following text would be used: | |
55 | ||
56 | ``SPDX-License-Identifier: BSD-3-Clause`` | |
57 | ||
58 | To label a file as dual-licensed with BSD-3-Clause and GPL-2.0 (e.g., for code | |
59 | that is shared between the kernel and userspace), the following text would be | |
60 | used: | |
61 | ||
62 | ``SPDX-License-Identifier: (BSD-3-Clause OR GPL-2.0)`` | |
63 | ||
64 | Refer to ``licenses/README`` for more details. | |
65 | ||
66 | Maintainers and Sub-trees | |
67 | ------------------------- | |
68 | ||
69 | The DPDK maintenance hierarchy is divided into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``. | |
70 | ||
71 | There are maintainers for the trees and for components within the tree. | |
72 | ||
73 | Trees and maintainers are listed in the ``MAINTAINERS`` file. For example:: | |
74 | ||
75 | Crypto Drivers | |
76 | -------------- | |
77 | M: Some Name <some.name@email.com> | |
78 | B: Another Name <another.name@email.com> | |
79 | T: git://dpdk.org/next/dpdk-next-crypto | |
80 | ||
81 | Intel AES-NI GCM PMD | |
82 | M: Some One <some.one@email.com> | |
83 | F: drivers/crypto/aesni_gcm/ | |
84 | F: doc/guides/cryptodevs/aesni_gcm.rst | |
85 | ||
86 | Where: | |
87 | ||
88 | * ``M`` is a tree or component maintainer. | |
89 | * ``B`` is a tree backup maintainer. | |
90 | * ``T`` is a repository tree. | |
91 | * ``F`` is a maintained file or directory. | |
92 | ||
93 | Additional details are given in the ``MAINTAINERS`` file. | |
94 | ||
95 | The role of the component maintainers is to: | |
96 | ||
97 | * Review patches for the component or delegate the review. | |
98 | The review should be done, ideally, within 1 week of submission to the mailing list. | |
99 | * Add an ``acked-by`` to patches, or patchsets, that are ready for committing to a tree. | |
100 | * Reply to questions asked about the component. | |
101 | ||
102 | Component maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file. | |
103 | Maintainers should have demonstrated a reasonable level of contributions or reviews to the component area. | |
104 | The maintainer should be confirmed by an ``ack`` from an established contributor. | |
105 | There can be more than one component maintainer if desired. | |
106 | ||
107 | The role of the tree maintainers is to: | |
108 | ||
109 | * Maintain the overall quality of their tree. | |
110 | This can entail additional review, compilation checks or other tests deemed necessary by the maintainer. | |
111 | * Commit patches that have been reviewed by component maintainers and/or other contributors. | |
112 | The tree maintainer should determine if patches have been reviewed sufficiently. | |
113 | * Ensure that patches are reviewed in a timely manner. | |
114 | * Prepare the tree for integration. | |
115 | * Ensure that there is a designated back-up maintainer and coordinate a handover for periods where the | |
116 | tree maintainer can't perform their role. | |
117 | ||
118 | Tree maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file. | |
119 | 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. | |
120 | The maintainer should be confirmed by an ``ack`` from an existing tree maintainer. | |
121 | Disagreements on trees or maintainers can be brought to the Technical Board. | |
122 | ||
123 | The backup maintainer for the master tree should be selected from the existing sub-tree maintainers from the project. | |
124 | The backup maintainer for a sub-tree should be selected from among the component maintainers within that sub-tree. | |
125 | ||
7c673cae FG |
126 | |
127 | Getting the Source Code | |
128 | ----------------------- | |
129 | ||
11fdf7f2 | 130 | The source code can be cloned using either of the following: |
7c673cae | 131 | |
11fdf7f2 | 132 | main repository:: |
7c673cae | 133 | |
11fdf7f2 | 134 | git clone git://dpdk.org/dpdk |
7c673cae FG |
135 | git clone http://dpdk.org/git/dpdk |
136 | ||
9f95a23c | 137 | sub-repositories (`list <http://git.dpdk.org/next>`_):: |
11fdf7f2 TL |
138 | |
139 | git clone git://dpdk.org/next/dpdk-next-* | |
140 | git clone http://dpdk.org/git/next/dpdk-next-* | |
7c673cae FG |
141 | |
142 | Make your Changes | |
143 | ----------------- | |
144 | ||
145 | Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines and requirements: | |
146 | ||
147 | * Follow the :ref:`coding_style` guidelines. | |
148 | ||
149 | * If you add new files or directories you should add your name to the ``MAINTAINERS`` file. | |
150 | ||
151 | * New external functions should be added to the local ``version.map`` file. | |
152 | See the :doc:`Guidelines for ABI policy and versioning </contributing/versioning>`. | |
153 | New external functions should also be added in alphabetical order. | |
154 | ||
155 | * Important changes will require an addition to the release notes in ``doc/guides/rel_notes/``. | |
156 | See the :ref:`Release Notes section of the Documentation Guidelines <doc_guidelines>` for details. | |
157 | ||
158 | * Test the compilation works with different targets, compilers and options, see :ref:`contrib_check_compilation`. | |
159 | ||
160 | * Don't break compilation between commits with forward dependencies in a patchset. | |
161 | Each commit should compile on its own to allow for ``git bisect`` and continuous integration testing. | |
162 | ||
11fdf7f2 | 163 | * Add tests to the ``app/test`` unit test framework where possible. |
7c673cae FG |
164 | |
165 | * Add documentation, if relevant, in the form of Doxygen comments or a User Guide in RST format. | |
166 | See the :ref:`Documentation Guidelines <doc_guidelines>`. | |
167 | ||
168 | Once the changes have been made you should commit them to your local repo. | |
169 | ||
170 | For small changes, that do not require specific explanations, it is better to keep things together in the | |
171 | same patch. | |
172 | Larger changes that require different explanations should be separated into logical patches in a patchset. | |
173 | A good way of thinking about whether a patch should be split is to consider whether the change could be | |
174 | applied without dependencies as a backport. | |
175 | ||
9f95a23c TL |
176 | It is better to keep the related documentation changes in the same patch |
177 | file as the code, rather than one big documentation patch at then end of a | |
178 | patchset. This makes it easier for future maintenance and development of the | |
179 | code. | |
180 | ||
7c673cae FG |
181 | As a guide to how patches should be structured run ``git log`` on similar files. |
182 | ||
183 | ||
184 | Commit Messages: Subject Line | |
185 | ----------------------------- | |
186 | ||
187 | The first, summary, line of the git commit message becomes the subject line of the patch email. | |
188 | Here are some guidelines for the summary line: | |
189 | ||
190 | * The summary line must capture the area and the impact of the change. | |
191 | ||
192 | * The summary line should be around 50 characters. | |
193 | ||
194 | * The summary line should be lowercase apart from acronyms. | |
195 | ||
196 | * It should be prefixed with the component name (use git log to check existing components). | |
197 | For example:: | |
198 | ||
199 | ixgbe: fix offload config option name | |
200 | ||
201 | config: increase max queues per port | |
202 | ||
203 | * Use the imperative of the verb (like instructions to the code base). | |
204 | ||
205 | * Don't add a period/full stop to the subject line or you will end up two in the patch name: ``dpdk_description..patch``. | |
206 | ||
207 | The actual email subject line should be prefixed by ``[PATCH]`` and the version, if greater than v1, | |
208 | for example: ``PATCH v2``. | |
209 | The is generally added by ``git send-email`` or ``git format-patch``, see below. | |
210 | ||
211 | If you are submitting an RFC draft of a feature you can use ``[RFC]`` instead of ``[PATCH]``. | |
212 | An RFC patch doesn't have to be complete. | |
213 | It is intended as a way of getting early feedback. | |
214 | ||
215 | ||
216 | Commit Messages: Body | |
217 | --------------------- | |
218 | ||
219 | Here are some guidelines for the body of a commit message: | |
220 | ||
221 | * The body of the message should describe the issue being fixed or the feature being added. | |
222 | It is important to provide enough information to allow a reviewer to understand the purpose of the patch. | |
223 | ||
224 | * When the change is obvious the body can be blank, apart from the signoff. | |
225 | ||
226 | * The commit message must end with a ``Signed-off-by:`` line which is added using:: | |
227 | ||
228 | git commit --signoff # or -s | |
229 | ||
230 | The purpose of the signoff is explained in the | |
11fdf7f2 | 231 | `Developer's Certificate of Origin <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1>`_ |
7c673cae FG |
232 | section of the Linux kernel guidelines. |
233 | ||
234 | .. Note:: | |
235 | ||
236 | All developers must ensure that they have read and understood the | |
237 | Developer's Certificate of Origin section of the documentation prior | |
238 | to applying the signoff and submitting a patch. | |
239 | ||
240 | * The signoff must be a real name and not an alias or nickname. | |
241 | More than one signoff is allowed. | |
242 | ||
243 | * The text of the commit message should be wrapped at 72 characters. | |
244 | ||
11fdf7f2 TL |
245 | * When fixing a regression, it is required to reference the id of the commit |
246 | which introduced the bug, and put the original author of that commit on CC. | |
247 | You can generate the required lines using the following git alias, which prints | |
248 | the commit SHA and the author of the original code:: | |
7c673cae | 249 | |
11fdf7f2 | 250 | git config alias.fixline "log -1 --abbrev=12 --format='Fixes: %h (\"%s\")%nCc: %ae'" |
7c673cae | 251 | |
11fdf7f2 | 252 | The output of ``git fixline <SHA>`` must then be added to the commit message:: |
7c673cae | 253 | |
11fdf7f2 | 254 | doc: fix some parameter description |
7c673cae | 255 | |
11fdf7f2 | 256 | Update the docs, fixing description of some parameter. |
7c673cae | 257 | |
11fdf7f2 TL |
258 | Fixes: abcdefgh1234 ("doc: add some parameter") |
259 | Cc: author@example.com | |
7c673cae FG |
260 | |
261 | Signed-off-by: Alex Smith <alex.smith@example.com> | |
262 | ||
263 | * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it. | |
264 | ||
265 | * Use correct capitalization, punctuation and spelling. | |
266 | ||
11fdf7f2 TL |
267 | In addition to the ``Signed-off-by:`` name the commit messages can also have |
268 | tags for who reported, suggested, tested and reviewed the patch being | |
269 | posted. Please refer to the `Tested, Acked and Reviewed by`_ section. | |
7c673cae | 270 | |
11fdf7f2 TL |
271 | Patch Fix Related Issues |
272 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
273 | ||
274 | `Coverity <https://scan.coverity.com/projects/dpdk-data-plane-development-kit>`_ | |
275 | is a tool for static code analysis. | |
276 | It is used as a cloud-based service used to scan the DPDK source code, | |
277 | and alert developers of any potential defects in the source code. | |
278 | When fixing an issue found by Coverity, the patch must contain a Coverity issue ID | |
279 | in the body of the commit message. For example:: | |
280 | ||
281 | ||
282 | doc: fix some parameter description | |
283 | ||
284 | Update the docs, fixing description of some parameter. | |
285 | ||
286 | Coverity issue: 12345 | |
287 | Fixes: abcdefgh1234 ("doc: add some parameter") | |
288 | Cc: author@example.com | |
289 | ||
290 | Signed-off-by: Alex Smith <alex.smith@example.com> | |
291 | ||
292 | ||
9f95a23c | 293 | `Bugzilla <https://bugs.dpdk.org>`_ |
11fdf7f2 TL |
294 | is a bug- or issue-tracking system. |
295 | Bug-tracking systems allow individual or groups of developers | |
296 | effectively to keep track of outstanding problems with their product. | |
297 | When fixing an issue raised in Bugzilla, the patch must contain | |
298 | a Bugzilla issue ID in the body of the commit message. | |
299 | For example:: | |
300 | ||
301 | doc: fix some parameter description | |
302 | ||
303 | Update the docs, fixing description of some parameter. | |
304 | ||
305 | Bugzilla ID: 12345 | |
306 | Fixes: abcdefgh1234 ("doc: add some parameter") | |
307 | Cc: author@example.com | |
308 | ||
309 | Signed-off-by: Alex Smith <alex.smith@example.com> | |
310 | ||
311 | Patch for Stable Releases | |
312 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
313 | ||
314 | All fix patches to the master branch that are candidates for backporting | |
9f95a23c | 315 | should also be CCed to the `stable@dpdk.org <http://mails.dpdk.org/listinfo/stable>`_ |
11fdf7f2 TL |
316 | mailing list. |
317 | In the commit message body the Cc: stable@dpdk.org should be inserted as follows:: | |
318 | ||
319 | doc: fix some parameter description | |
320 | ||
321 | Update the docs, fixing description of some parameter. | |
322 | ||
323 | Fixes: abcdefgh1234 ("doc: add some parameter") | |
324 | Cc: stable@dpdk.org | |
325 | ||
326 | Signed-off-by: Alex Smith <alex.smith@example.com> | |
327 | ||
328 | For further information on stable contribution you can go to | |
329 | :doc:`Stable Contribution Guide <stable>`. | |
7c673cae FG |
330 | |
331 | ||
332 | Creating Patches | |
333 | ---------------- | |
334 | ||
335 | It is possible to send patches directly from git but for new contributors it is recommended to generate the | |
336 | patches with ``git format-patch`` and then when everything looks okay, and the patches have been checked, to | |
337 | send them with ``git send-email``. | |
338 | ||
339 | Here are some examples of using ``git format-patch`` to generate patches: | |
340 | ||
341 | .. code-block:: console | |
342 | ||
343 | # Generate a patch from the last commit. | |
344 | git format-patch -1 | |
345 | ||
346 | # Generate a patch from the last 3 commits. | |
347 | git format-patch -3 | |
348 | ||
349 | # Generate the patches in a directory. | |
350 | git format-patch -3 -o ~/patch/ | |
351 | ||
352 | # Add a cover letter to explain a patchset. | |
353 | git format-patch -3 -o ~/patch/ --cover-letter | |
354 | ||
355 | # Add a prefix with a version number. | |
356 | git format-patch -3 -o ~/patch/ -v 2 | |
357 | ||
358 | ||
359 | Cover letters are useful for explaining a patchset and help to generate a logical threading to the patches. | |
360 | Smaller notes can be put inline in the patch after the ``---`` separator, for example:: | |
361 | ||
362 | Subject: [PATCH] fm10k/base: add FM10420 device ids | |
363 | ||
364 | Add the device ID for Boulder Rapids and Atwood Channel to enable | |
365 | drivers to support those devices. | |
366 | ||
367 | Signed-off-by: Alex Smith <alex.smith@example.com> | |
368 | --- | |
369 | ||
370 | ADD NOTES HERE. | |
371 | ||
372 | drivers/net/fm10k/base/fm10k_api.c | 6 ++++++ | |
373 | drivers/net/fm10k/base/fm10k_type.h | 6 ++++++ | |
374 | 2 files changed, 12 insertions(+) | |
375 | ... | |
376 | ||
377 | Version 2 and later of a patchset should also include a short log of the changes so the reviewer knows what has changed. | |
378 | This can be added to the cover letter or the annotations. | |
379 | For example:: | |
380 | ||
381 | --- | |
382 | v3: | |
383 | * Fixed issued with version.map. | |
384 | ||
385 | v2: | |
386 | * Added i40e support. | |
387 | * Renamed ethdev functions from rte_eth_ieee15888_*() to rte_eth_timesync_*() | |
388 | since 802.1AS can be supported through the same interfaces. | |
389 | ||
390 | ||
391 | .. _contrib_checkpatch: | |
392 | ||
393 | Checking the Patches | |
394 | -------------------- | |
395 | ||
11fdf7f2 | 396 | Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``devtools`` |
7c673cae FG |
397 | directory of the DPDK repo. |
398 | This uses the Linux kernel development tool ``checkpatch.pl`` which can be obtained by cloning, and periodically, | |
399 | updating the Linux kernel sources. | |
400 | ||
401 | The path to the original Linux script must be set in the environment variable ``DPDK_CHECKPATCH_PATH``. | |
402 | This, and any other configuration variables required by the development tools, are loaded from the following | |
403 | files, in order of preference:: | |
404 | ||
405 | .develconfig | |
406 | ~/.config/dpdk/devel.config | |
407 | /etc/dpdk/devel.config. | |
408 | ||
409 | Once the environment variable the script can be run as follows:: | |
410 | ||
11fdf7f2 | 411 | devtools/checkpatches.sh ~/patch/ |
7c673cae FG |
412 | |
413 | The script usage is:: | |
414 | ||
415 | checkpatches.sh [-h] [-q] [-v] [patch1 [patch2] ...]]" | |
416 | ||
417 | Where: | |
418 | ||
419 | * ``-h``: help, usage. | |
420 | * ``-q``: quiet. Don't output anything for files without issues. | |
421 | * ``-v``: verbose. | |
422 | * ``patchX``: path to one or more patches. | |
423 | ||
424 | Then the git logs should be checked using the ``check-git-log.sh`` script. | |
425 | ||
426 | The script usage is:: | |
427 | ||
428 | check-git-log.sh [range] | |
429 | ||
430 | Where the range is a ``git log`` option. | |
431 | ||
432 | ||
433 | .. _contrib_check_compilation: | |
434 | ||
435 | Checking Compilation | |
436 | -------------------- | |
437 | ||
9f95a23c TL |
438 | Makefile System |
439 | ~~~~~~~~~~~~~~~ | |
440 | ||
11fdf7f2 | 441 | Compilation of patches and changes should be tested using the ``test-build.sh`` script in the ``devtools`` |
7c673cae FG |
442 | directory of the DPDK repo:: |
443 | ||
9f95a23c | 444 | devtools/test-build.sh x86_64-native-linux-gcc+next+shared |
7c673cae FG |
445 | |
446 | The script usage is:: | |
447 | ||
448 | test-build.sh [-h] [-jX] [-s] [config1 [config2] ...]] | |
449 | ||
450 | Where: | |
451 | ||
452 | * ``-h``: help, usage. | |
453 | * ``-jX``: use X parallel jobs in "make". | |
454 | * ``-s``: short test with only first config and without examples/doc. | |
455 | * ``config``: default config name plus config switches delimited with a ``+`` sign. | |
456 | ||
457 | Examples of configs are:: | |
458 | ||
9f95a23c TL |
459 | x86_64-native-linux-gcc |
460 | x86_64-native-linux-gcc+next+shared | |
461 | x86_64-native-linux-clang+shared | |
7c673cae | 462 | |
11fdf7f2 | 463 | The builds can be modified via the following environmental variables: |
7c673cae FG |
464 | |
465 | * ``DPDK_BUILD_TEST_CONFIGS`` (target1+option1+option2 target2) | |
466 | * ``DPDK_DEP_CFLAGS`` | |
467 | * ``DPDK_DEP_LDFLAGS`` | |
7c673cae FG |
468 | * ``DPDK_DEP_PCAP`` (y/[n]) |
469 | * ``DPDK_NOTIFY`` (notify-send) | |
470 | ||
471 | These can be set from the command line or in the config files shown above in the :ref:`contrib_checkpatch`. | |
472 | ||
473 | The recommended configurations and options to test compilation prior to submitting patches are:: | |
474 | ||
9f95a23c TL |
475 | x86_64-native-linux-gcc+shared+next |
476 | x86_64-native-linux-clang+shared | |
477 | i686-native-linux-gcc | |
7c673cae FG |
478 | |
479 | export DPDK_DEP_ZLIB=y | |
480 | export DPDK_DEP_PCAP=y | |
481 | export DPDK_DEP_SSL=y | |
482 | ||
9f95a23c TL |
483 | Meson System |
484 | ~~~~~~~~~~~~ | |
485 | ||
486 | Compilation of patches is to be tested with ``devtools/test-meson-builds.sh`` script. | |
487 | ||
488 | The script internally checks for dependencies, then builds for several | |
489 | combinations of compilation configuration. | |
490 | ||
7c673cae FG |
491 | |
492 | Sending Patches | |
493 | --------------- | |
494 | ||
495 | Patches should be sent to the mailing list using ``git send-email``. | |
496 | You can configure an external SMTP with something like the following:: | |
497 | ||
498 | [sendemail] | |
499 | smtpuser = name@domain.com | |
500 | smtpserver = smtp.domain.com | |
501 | smtpserverport = 465 | |
502 | smtpencryption = ssl | |
503 | ||
504 | See the `Git send-email <https://git-scm.com/docs/git-send-email>`_ documentation for more details. | |
505 | ||
506 | The patches should be sent to ``dev@dpdk.org``. | |
507 | If the patches are a change to existing files then you should send them TO the maintainer(s) and CC ``dev@dpdk.org``. | |
508 | The appropriate maintainer can be found in the ``MAINTAINERS`` file:: | |
509 | ||
510 | git send-email --to maintainer@some.org --cc dev@dpdk.org 000*.patch | |
511 | ||
11fdf7f2 TL |
512 | Script ``get-maintainer.sh`` can be used to select maintainers automatically:: |
513 | ||
514 | git send-email --to-cmd ./devtools/get-maintainer.sh --cc dev@dpdk.org 000*.patch | |
515 | ||
7c673cae FG |
516 | New additions can be sent without a maintainer:: |
517 | ||
518 | git send-email --to dev@dpdk.org 000*.patch | |
519 | ||
520 | You can test the emails by sending it to yourself or with the ``--dry-run`` option. | |
521 | ||
522 | If the patch is in relation to a previous email thread you can add it to the same thread using the Message ID:: | |
523 | ||
524 | git send-email --to dev@dpdk.org --in-reply-to <1234-foo@bar.com> 000*.patch | |
525 | ||
526 | The Message ID can be found in the raw text of emails or at the top of each Patchwork patch, | |
9f95a23c | 527 | `for example <http://patches.dpdk.org/patch/7646/>`_. |
7c673cae FG |
528 | Shallow threading (``--thread --no-chain-reply-to``) is preferred for a patch series. |
529 | ||
530 | Once submitted your patches will appear on the mailing list and in Patchwork. | |
531 | ||
532 | Experienced committers may send patches directly with ``git send-email`` without the ``git format-patch`` step. | |
533 | The options ``--annotate`` and ``confirm = always`` are recommended for checking patches before sending. | |
534 | ||
535 | ||
11fdf7f2 TL |
536 | Backporting patches for Stable Releases |
537 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
538 | ||
539 | Sometimes a maintainer or contributor wishes, or can be asked, to send a patch | |
540 | for a stable release rather than mainline. | |
541 | In this case the patch(es) should be sent to ``stable@dpdk.org``, | |
542 | not to ``dev@dpdk.org``. | |
543 | ||
544 | Given that there are multiple stable releases being maintained at the same time, | |
545 | please specify exactly which branch(es) the patch is for | |
546 | using ``git send-email --subject-prefix='PATCH 16.11' ...`` | |
547 | and also optionally in the cover letter or in the annotation. | |
548 | ||
549 | ||
7c673cae FG |
550 | The Review Process |
551 | ------------------ | |
552 | ||
11fdf7f2 TL |
553 | Patches are reviewed by the community, relying on the experience and |
554 | collaboration of the members to double-check each other's work. There are a | |
555 | number of ways to indicate that you have checked a patch on the mailing list. | |
7c673cae | 556 | |
11fdf7f2 TL |
557 | |
558 | Tested, Acked and Reviewed by | |
559 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
560 | ||
561 | To indicate that you have interacted with a patch on the mailing list you | |
562 | should respond to the patch in an email with one of the following tags: | |
563 | ||
564 | * Reviewed-by: | |
565 | * Acked-by: | |
566 | * Tested-by: | |
567 | * Reported-by: | |
568 | * Suggested-by: | |
569 | ||
570 | The tag should be on a separate line as follows:: | |
571 | ||
572 | tag-here: Name Surname <email@address.com> | |
573 | ||
574 | Each of these tags has a specific meaning. In general, the DPDK community | |
575 | follows the kernel usage of the tags. A short summary of the meanings of each | |
576 | tag is given here for reference: | |
577 | ||
578 | .. _statement: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight | |
579 | ||
580 | ``Reviewed-by:`` is a strong statement_ that the patch is an appropriate state | |
581 | for merging without any remaining serious technical issues. Reviews from | |
582 | community members who are known to understand the subject area and to perform | |
583 | thorough reviews will increase the likelihood of the patch getting merged. | |
584 | ||
585 | ``Acked-by:`` is a record that the person named was not directly involved in | |
586 | the preparation of the patch but wishes to signify and record their acceptance | |
587 | and approval of it. | |
588 | ||
589 | ``Tested-by:`` indicates that the patch has been successfully tested (in some | |
590 | environment) by the person named. | |
591 | ||
592 | ``Reported-by:`` is used to acknowledge person who found or reported the bug. | |
593 | ||
594 | ``Suggested-by:`` indicates that the patch idea was suggested by the named | |
595 | person. | |
596 | ||
597 | ||
598 | ||
599 | Steps to getting your patch merged | |
600 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
601 | ||
602 | The more work you put into the previous steps the easier it will be to get a | |
603 | patch accepted. The general cycle for patch review and acceptance is: | |
7c673cae FG |
604 | |
605 | #. Submit the patch. | |
606 | ||
607 | #. Check the automatic test reports in the coming hours. | |
608 | ||
609 | #. Wait for review comments. While you are waiting review some other patches. | |
610 | ||
611 | #. Fix the review comments and submit a ``v n+1`` patchset:: | |
612 | ||
613 | git format-patch -3 -v 2 | |
614 | ||
615 | #. Update Patchwork to mark your previous patches as "Superseded". | |
616 | ||
617 | #. If the patch is deemed suitable for merging by the relevant maintainer(s) or other developers they will ``ack`` | |
618 | the patch with an email that includes something like:: | |
619 | ||
620 | Acked-by: Alex Smith <alex.smith@example.com> | |
621 | ||
622 | **Note**: When acking patches please remove as much of the text of the patch email as possible. | |
623 | It is generally best to delete everything after the ``Signed-off-by:`` line. | |
624 | ||
625 | #. Having the patch ``Reviewed-by:`` and/or ``Tested-by:`` will also help the patch to be accepted. | |
626 | ||
627 | #. If the patch isn't deemed suitable based on being out of scope or conflicting with existing functionality | |
628 | it may receive a ``nack``. | |
629 | In this case you will need to make a more convincing technical argument in favor of your patches. | |
630 | ||
631 | #. In addition a patch will not be accepted if it doesn't address comments from a previous version with fixes or | |
632 | valid arguments. | |
633 | ||
11fdf7f2 TL |
634 | #. It is the responsibility of a maintainer to ensure that patches are reviewed and to provide an ``ack`` or |
635 | ``nack`` of those patches as appropriate. | |
636 | ||
637 | #. Once a patch has been acked by the relevant maintainer, reviewers may still comment on it for a further | |
638 | two weeks. After that time, the patch should be merged into the relevant git tree for the next release. | |
639 | Additional notes and restrictions: | |
640 | ||
641 | * Patches should be acked by a maintainer at least two days before the release merge | |
642 | deadline, in order to make that release. | |
643 | * For patches acked with less than two weeks to go to the merge deadline, all additional | |
644 | comments should be made no later than two days before the merge deadline. | |
645 | * After the appropriate time for additional feedback has passed, if the patch has not yet | |
646 | been merged to the relevant tree by the committer, it should be treated as though it had, | |
647 | in that any additional changes needed to it must be addressed by a follow-on patch, rather | |
648 | than rework of the original. | |
649 | * Trivial patches may be merged sooner than described above at the tree committer's | |
650 | discretion. | |
651 | ||
652 | DPDK Maintainers | |
653 | ---------------- | |
654 | ||
655 | The following are the DPDK maintainers as listed in the ``MAINTAINERS`` file | |
656 | in the DPDK root directory. | |
657 | ||
658 | .. literalinclude:: ../../../MAINTAINERS | |
659 | :lines: 3- |