+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright 2018 The DPDK contributors
+
.. submitting_patches:
Contributing Code to DPDK
This document outlines the guidelines for submitting code to DPDK.
-The DPDK development process is modelled (loosely) on the Linux Kernel development model so it is worth reading the
+The DPDK development process is modeled (loosely) on the Linux Kernel development model so it is worth reading the
Linux kernel guide on submitting patches:
`How to Get Your Change Into the Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_.
The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines.
* All sub-repositories are merged into main repository for ``-rc1`` and ``-rc2`` versions of the release.
* After the ``-rc2`` release all patches should target the main repository.
-The mailing list for DPDK development is `dev@dpdk.org <http://dpdk.org/ml/archives/dev/>`_.
-Contributors will need to `register for the mailing list <http://dpdk.org/ml/listinfo/dev>`_ in order to submit patches.
-It is also worth registering for the DPDK `Patchwork <http://dpdk.org/dev/patchwork/project/dpdk/list/>`_
+The mailing list for DPDK development is `dev@dpdk.org <https://mails.dpdk.org/archives/dev/>`_.
+Contributors will need to `register for the mailing list <https://mails.dpdk.org/listinfo/dev>`_ in order to submit patches.
+It is also worth registering for the DPDK `Patchwork <https://patches.dpdk.org/project/dpdk/list/>`_
+
+If you are using the GitHub service, pushing to a branch will trigger GitHub
+Actions to automatically build your changes and run unit tests and ABI checks.
+
+Additionally, a Travis configuration is available in DPDK but Travis free usage
+is limited to a few builds.
+You can link your repository to the ``travis-ci.com`` build service.
The development process requires some familiarity with the ``git`` version control system.
Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information.
Crypto Drivers
--------------
M: Some Name <some.name@email.com>
- B: Another Name <another.name@email.com>
T: git://dpdk.org/next/dpdk-next-crypto
Intel AES-NI GCM PMD
Where:
* ``M`` is a tree or component maintainer.
-* ``B`` is a tree backup maintainer.
* ``T`` is a repository tree.
* ``F`` is a maintained file or directory.
The maintainer should be confirmed by an ``ack`` from an existing tree maintainer.
Disagreements on trees or maintainers can be brought to the Technical Board.
-The backup maintainer for the master tree should be selected from the existing sub-tree maintainers from the project.
+The backup maintainer for the main tree should be selected
+from the existing sub-tree maintainers of the project.
The backup maintainer for a sub-tree should be selected from among the component maintainers within that sub-tree.
main repository::
git clone git://dpdk.org/dpdk
- git clone http://dpdk.org/git/dpdk
+ git clone https://dpdk.org/git/dpdk
-sub-repositories (`list <http://dpdk.org/browse/next>`_)::
+sub-repositories (`list <https://git.dpdk.org/next>`_)::
git clone git://dpdk.org/next/dpdk-next-*
- git clone http://dpdk.org/git/next/dpdk-next-*
+ git clone https://dpdk.org/git/next/dpdk-next-*
Make your Changes
-----------------
* If you add new files or directories you should add your name to the ``MAINTAINERS`` file.
-* New external functions should be added to the local ``version.map`` file.
- See the :doc:`Guidelines for ABI policy and versioning </contributing/versioning>`.
- New external functions should also be added in alphabetical order.
+* Initial submission of new PMDs should be prepared against a corresponding repo.
+
+ * Thus, for example, initial submission of a new network PMD should be
+ prepared against dpdk-next-net repo.
+
+ * Likewise, initial submission of a new crypto or compression PMD should be
+ prepared against dpdk-next-crypto repo.
+
+ * For other PMDs and more info, refer to the ``MAINTAINERS`` file.
+
+* New external functions should be added to the local ``version.map`` file. See
+ the :doc:`ABI policy <abi_policy>` and :ref:`ABI versioning <abi_versioning>`
+ guides. New external functions should also be added in alphabetical order.
* Important changes will require an addition to the release notes in ``doc/guides/rel_notes/``.
See the :ref:`Release Notes section of the Documentation Guidelines <doc_guidelines>` for details.
* Don't break compilation between commits with forward dependencies in a patchset.
Each commit should compile on its own to allow for ``git bisect`` and continuous integration testing.
-* Add tests to the the ``app/test`` unit test framework where possible.
+* Add tests to the ``app/test`` unit test framework where possible.
* Add documentation, if relevant, in the form of Doxygen comments or a User Guide in RST format.
See the :ref:`Documentation Guidelines <doc_guidelines>`.
A good way of thinking about whether a patch should be split is to consider whether the change could be
applied without dependencies as a backport.
+It is better to keep the related documentation changes in the same patch
+file as the code, rather than one big documentation patch at the end of a
+patchset. This makes it easier for future maintenance and development of the
+code.
+
As a guide to how patches should be structured run ``git log`` on similar files.
tags for who reported, suggested, tested and reviewed the patch being
posted. Please refer to the `Tested, Acked and Reviewed by`_ section.
+Patch Fix Related Issues
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Coverity <https://scan.coverity.com/projects/dpdk-data-plane-development-kit>`_
+is a tool for static code analysis.
+It is used as a cloud-based service used to scan the DPDK source code,
+and alert developers of any potential defects in the source code.
+When fixing an issue found by Coverity, the patch must contain a Coverity issue ID
+in the body of the commit message. For example::
+
+
+ doc: fix some parameter description
+
+ Update the docs, fixing description of some parameter.
+
+ Coverity issue: 12345
+ Fixes: abcdefgh1234 ("doc: add some parameter")
+ Cc: author@example.com
+
+ Signed-off-by: Alex Smith <alex.smith@example.com>
+
+
+`Bugzilla <https://bugs.dpdk.org>`_
+is a bug- or issue-tracking system.
+Bug-tracking systems allow individual or groups of developers
+effectively to keep track of outstanding problems with their product.
+When fixing an issue raised in Bugzilla, the patch must contain
+a Bugzilla issue ID in the body of the commit message.
+For example::
+
+ doc: fix some parameter description
+
+ Update the docs, fixing description of some parameter.
+
+ Bugzilla ID: 12345
+ Fixes: abcdefgh1234 ("doc: add some parameter")
+ Cc: author@example.com
+
+ Signed-off-by: Alex Smith <alex.smith@example.com>
+
+Patch for Stable Releases
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All fix patches to the main branch that are candidates for backporting
+should also be CCed to the `stable@dpdk.org <https://mails.dpdk.org/listinfo/stable>`_
+mailing list.
+In the commit message body the Cc: stable@dpdk.org should be inserted as follows::
+
+ doc: fix some parameter description
+
+ Update the docs, fixing description of some parameter.
+
+ Fixes: abcdefgh1234 ("doc: add some parameter")
+ Cc: stable@dpdk.org
+
+ Signed-off-by: Alex Smith <alex.smith@example.com>
+
+For further information on stable contribution you can go to
+:doc:`Stable Contribution Guide <stable>`.
+
+Patch Dependencies
+~~~~~~~~~~~~~~~~~~
+
+Sometimes a patch or patchset can depend on another one.
+To help the maintainers and automation tasks, please document this dependency in commit log or cover letter
+with the following syntax:
+
+``Depends-on: series-NNNNN ("Title of the series")`` or ``Depends-on: patch-NNNNN ("Title of the patch")``
+
+Where ``NNNNN`` is patchwork ID for patch or series::
+
+ doc: fix some parameter description
+
+ Update the docs, fixing description of some parameter.
+
+ Signed-off-by: Alex Smith <alex.smith@example.com>
+ ---
+ Depends-on: series-10000 ("Title of the series")
Creating Patches
----------------
updating the Linux kernel sources.
The path to the original Linux script must be set in the environment variable ``DPDK_CHECKPATCH_PATH``.
-This, and any other configuration variables required by the development tools, are loaded from the following
-files, in order of preference::
+
+Spell checking of commonly misspelled words is enabled
+by default if installed in ``/usr/share/codespell/dictionary.txt``.
+A different dictionary path can be specified
+in the environment variable ``DPDK_CHECKPATCH_CODESPELL``.
+
+There is a DPDK script to build an adjusted dictionary
+from the multiple codespell dictionaries::
+
+ git clone https://github.com/codespell-project/codespell.git
+ devtools/build-dict.sh codespell/ > codespell-dpdk.txt
+
+Environment variables required by the development tools,
+are loaded from the following files, in order of preference::
.develconfig
~/.config/dpdk/devel.config
/etc/dpdk/devel.config.
-Once the environment variable the script can be run as follows::
+Once the environment variable is set, the script can be run as follows::
devtools/checkpatches.sh ~/patch/
The script usage is::
- checkpatches.sh [-h] [-q] [-v] [patch1 [patch2] ...]]"
-
-Where:
-
-* ``-h``: help, usage.
-* ``-q``: quiet. Don't output anything for files without issues.
-* ``-v``: verbose.
-* ``patchX``: path to one or more patches.
+ checkpatches.sh [-h] [-q] [-v] [-nX|-r range|patch1 [patch2] ...]
Then the git logs should be checked using the ``check-git-log.sh`` script.
The script usage is::
- check-git-log.sh [range]
-
-Where the range is a ``git log`` option.
+ check-git-log.sh [-h] [-nX|-r range]
+For both of the above scripts, the -n option is used to specify a number of commits from HEAD,
+and the -r option allows the user specify a ``git log`` range.
.. _contrib_check_compilation:
Checking Compilation
--------------------
-Compilation of patches and changes should be tested using the the ``test-build.sh`` script in the ``devtools``
-directory of the DPDK repo::
-
- devtools/test-build.sh x86_64-native-linuxapp-gcc+next+shared
-
-The script usage is::
-
- test-build.sh [-h] [-jX] [-s] [config1 [config2] ...]]
-
-Where:
+Compilation of patches is to be tested with ``devtools/test-meson-builds.sh`` script.
-* ``-h``: help, usage.
-* ``-jX``: use X parallel jobs in "make".
-* ``-s``: short test with only first config and without examples/doc.
-* ``config``: default config name plus config switches delimited with a ``+`` sign.
+The script internally checks for dependencies, then builds for several
+combinations of compilation configuration.
+By default, each build will be put in a subfolder of the current working directory.
+However, if it is preferred to place the builds in a different location,
+the environment variable ``DPDK_BUILD_TEST_DIR`` can be set to that desired location.
+For example, setting ``DPDK_BUILD_TEST_DIR=__builds`` will put all builds
+in a single subfolder called "__builds" created in the current directory.
+Setting ``DPDK_BUILD_TEST_DIR`` to an absolute directory path e.g. ``/tmp`` is also supported.
-Examples of configs are::
- x86_64-native-linuxapp-gcc
- x86_64-native-linuxapp-gcc+next+shared
- x86_64-native-linuxapp-clang+shared
+.. _integrated_abi_check:
-The builds can be modified via the following environmental variables:
+Checking ABI compatibility
+--------------------------
-* ``DPDK_BUILD_TEST_CONFIGS`` (target1+option1+option2 target2)
-* ``DPDK_DEP_CFLAGS``
-* ``DPDK_DEP_LDFLAGS``
-* ``DPDK_DEP_PCAP`` (y/[n])
-* ``DPDK_NOTIFY`` (notify-send)
+By default, ABI compatibility checks are disabled.
-These can be set from the command line or in the config files shown above in the :ref:`contrib_checkpatch`.
+To enable them, a reference version must be selected via the environment
+variable ``DPDK_ABI_REF_VERSION``. Contributors should ordinarily reference the
+git tag of the most recent release of DPDK in ``DPDK_ABI_REF_VERSION``.
-The recommended configurations and options to test compilation prior to submitting patches are::
+The ``devtools/test-meson-builds.sh`` script then build this reference version
+in a temporary directory and store the results in a subfolder of the current
+working directory.
+The environment variable ``DPDK_ABI_REF_DIR`` can be set so that the results go
+to a different location.
- x86_64-native-linuxapp-gcc+shared+next
- x86_64-native-linuxapp-clang+shared
- i686-native-linuxapp-gcc
+Sample::
- export DPDK_DEP_ZLIB=y
- export DPDK_DEP_PCAP=y
- export DPDK_DEP_SSL=y
+ DPDK_ABI_REF_VERSION=v19.11 DPDK_ABI_REF_DIR=/tmp ./devtools/test-meson-builds.sh
Sending Patches
git send-email --to dev@dpdk.org --in-reply-to <1234-foo@bar.com> 000*.patch
The Message ID can be found in the raw text of emails or at the top of each Patchwork patch,
-`for example <http://dpdk.org/dev/patchwork/patch/7646/>`_.
+`for example <https://patches.dpdk.org/patch/7646/>`_.
Shallow threading (``--thread --no-chain-reply-to``) is preferred for a patch series.
Once submitted your patches will appear on the mailing list and in Patchwork.
The options ``--annotate`` and ``confirm = always`` are recommended for checking patches before sending.
+Backporting patches for Stable Releases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes a maintainer or contributor wishes, or can be asked, to send a patch
+for a stable release rather than mainline.
+In this case the patch(es) should be sent to ``stable@dpdk.org``,
+not to ``dev@dpdk.org``.
+
+Given that there are multiple stable releases being maintained at the same time,
+please specify exactly which branch(es) the patch is for
+using ``git send-email --subject-prefix='PATCH 16.11' ...``
+and also optionally in the cover letter or in the annotation.
+
+
The Review Process
------------------