X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fpatches.rst;h=16b40225f25fb1c43b7075e6fffefd9634b156d5;hb=3d4b2afb73f7f0988f8e66ba1b37f2a446e33868;hp=7926c965d399775c4e73f51fb307ea8a0a6c403d;hpb=1e46fadefeeb2a60aa58df6c5adc655de337977f;p=dpdk.git diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst index 7926c965d3..16b40225f2 100644 --- a/doc/guides/contributing/patches.rst +++ b/doc/guides/contributing/patches.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 The DPDK contributors + .. submitting_patches: Contributing Code to DPDK @@ -5,7 +8,7 @@ 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 `_. The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines. @@ -25,13 +28,40 @@ The DPDK development process has the following features: * 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 `_. -Contributors will need to `register for the mailing list `_ in order to submit patches. -It is also worth registering for the DPDK `Patchwork `_ +The mailing list for DPDK development is `dev@dpdk.org `_. +Contributors will need to `register for the mailing list `_ in order to submit patches. +It is also worth registering for the DPDK `Patchwork `_ + +If you are using the GitHub service, you can link your repository to +the ``travis-ci.org`` build service. When you push patches to your GitHub +repository, the travis service will automatically build your changes. The development process requires some familiarity with the ``git`` version control system. Refer to the `Pro Git Book `_ for further information. +Source License +-------------- + +The DPDK uses the Open Source BSD-3-Clause license for the core libraries and +drivers. The kernel components are GPL-2.0 licensed. DPDK uses single line +reference to Unique License Identifiers in source files as defined by the Linux +Foundation's `SPDX project `_. + +DPDK uses first line of the file to be SPDX tag. In case of *#!* scripts, SPDX +tag can be placed in 2nd line of the file. + +For example, to label a file as subject to the BSD-3-Clause license, +the following text would be used: + +``SPDX-License-Identifier: BSD-3-Clause`` + +To label a file as dual-licensed with BSD-3-Clause and GPL-2.0 (e.g., for code +that is shared between the kernel and userspace), the following text would be +used: + +``SPDX-License-Identifier: (BSD-3-Clause OR GPL-2.0)`` + +Refer to ``licenses/README`` for more details. Maintainers and Sub-trees ------------------------- @@ -45,7 +75,6 @@ Trees and maintainers are listed in the ``MAINTAINERS`` file. For example:: Crypto Drivers -------------- M: Some Name - B: Another Name T: git://dpdk.org/next/dpdk-next-crypto Intel AES-NI GCM PMD @@ -56,7 +85,6 @@ Trees and maintainers are listed in the ``MAINTAINERS`` file. For example:: 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. @@ -102,12 +130,12 @@ The source code can be cloned using either of the following: 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 `_):: +sub-repositories (`list `_):: 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 ----------------- @@ -118,9 +146,19 @@ Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines * 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 `. - 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 ` and :ref:`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 ` for details. @@ -130,7 +168,7 @@ Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines * 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 `. @@ -143,6 +181,11 @@ Larger changes that require different explanations should be separated into logi 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. @@ -207,18 +250,21 @@ Here are some guidelines for the body of a commit message: * The text of the commit message should be wrapped at 72 characters. -* When fixing a regression, it is a good idea to reference the id of the commit which introduced the bug. - You can generate the required text using the following git alias:: +* When fixing a regression, it is required to reference the id of the commit + which introduced the bug, and put the original author of that commit on CC. + You can generate the required lines using the following git alias, which prints + the commit SHA and the author of the original code:: - git config alias.fixline "log -1 --abbrev=12 --format='Fixes: %h (\"%s\")'" + git config alias.fixline "log -1 --abbrev=12 --format='Fixes: %h (\"%s\")%nCc: %ae'" - The ``Fixes:`` line can then be added to the commit message:: + The output of ``git fixline `` must then be added to the commit message:: - doc: fix vhost sample parameter + doc: fix some parameter description - Update the docs to reflect removed dev-index. + Update the docs, fixing description of some parameter. - Fixes: 17b8320a3e11 ("vhost: remove index parameter") + Fixes: abcdefgh1234 ("doc: add some parameter") + Cc: author@example.com Signed-off-by: Alex Smith @@ -230,6 +276,66 @@ In addition to the ``Signed-off-by:`` name the commit messages can also have 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 `_ +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 + + +`Bugzilla `_ +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 + +Patch for Stable Releases +~~~~~~~~~~~~~~~~~~~~~~~~~ + +All fix patches to the master branch that are candidates for backporting +should also be CCed to the `stable@dpdk.org `_ +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 + +For further information on stable contribution you can go to +:doc:`Stable Contribution Guide `. + Creating Patches ---------------- @@ -301,14 +407,23 @@ This uses the Linux kernel development tool ``checkpatch.pl`` which can be obta 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 +can be enabled by downloading the codespell dictionary:: + + https://raw.githubusercontent.com/codespell-project/codespell/master/codespell_lib/data/dictionary.txt + +The path to the downloaded ``dictionary.txt`` must be set +in the environment variable ``DPDK_CHECKPATCH_CODESPELL``. + +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/ @@ -337,10 +452,13 @@ Where the range is a ``git log`` option. Checking Compilation -------------------- -Compilation of patches and changes should be tested using the the ``test-build.sh`` script in the ``devtools`` +Makefile System +~~~~~~~~~~~~~~~ + +Compilation of patches and changes should be tested using the ``test-build.sh`` script in the ``devtools`` directory of the DPDK repo:: - devtools/test-build.sh x86_64-native-linuxapp-gcc+next+shared + devtools/test-build.sh x86_64-native-linux-gcc+next+shared The script usage is:: @@ -355,16 +473,16 @@ Where: Examples of configs are:: - x86_64-native-linuxapp-gcc - x86_64-native-linuxapp-gcc+next+shared - x86_64-native-linuxapp-clang+shared + x86_64-native-linux-gcc + x86_64-native-linux-gcc+next+shared + x86_64-native-linux-clang+shared The builds can be modified via the following environmental variables: * ``DPDK_BUILD_TEST_CONFIGS`` (target1+option1+option2 target2) +* ``DPDK_BUILD_TEST_DIR`` * ``DPDK_DEP_CFLAGS`` * ``DPDK_DEP_LDFLAGS`` -* ``DPDK_DEP_MOFED`` (y/[n]) * ``DPDK_DEP_PCAP`` (y/[n]) * ``DPDK_NOTIFY`` (notify-send) @@ -372,14 +490,45 @@ These can be set from the command line or in the config files shown above in the The recommended configurations and options to test compilation prior to submitting patches are:: - x86_64-native-linuxapp-gcc+shared+next - x86_64-native-linuxapp-clang+shared - i686-native-linuxapp-gcc + x86_64-native-linux-gcc+shared+next + x86_64-native-linux-clang+shared + i686-native-linux-gcc export DPDK_DEP_ZLIB=y export DPDK_DEP_PCAP=y export DPDK_DEP_SSL=y +Meson System +~~~~~~~~~~~~ + +Compilation of patches is to be tested with ``devtools/test-meson-builds.sh`` script. + +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. + + +.. _integrated_abi_check: + +Checking ABI compatibility +-------------------------- + +By default, ABI compatibility checks are disabled. + +To enable them, a reference version must be selected via the environment +variable ``DPDK_ABI_REF_VERSION``. + +The ``devtools/test-build.sh`` and ``devtools/test-meson-builds.sh`` scripts +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. + Sending Patches --------------- @@ -401,6 +550,10 @@ The appropriate maintainer can be found in the ``MAINTAINERS`` file:: git send-email --to maintainer@some.org --cc dev@dpdk.org 000*.patch +Script ``get-maintainer.sh`` can be used to select maintainers automatically:: + + git send-email --to-cmd ./devtools/get-maintainer.sh --cc dev@dpdk.org 000*.patch + New additions can be sent without a maintainer:: git send-email --to dev@dpdk.org 000*.patch @@ -412,7 +565,7 @@ If the patch is in relation to a previous email thread you can add it to the sam 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 `_. +`for example `_. 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. @@ -421,6 +574,20 @@ Experienced committers may send patches directly with ``git send-email`` without 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 ------------------