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