X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fpatches.rst;h=6dbbd5f8d104ea4f14098adc81987e551cd4ec6d;hb=e32b525aae84023292edf5d2ef2fb78cc340ef14;hp=3b2b174ada3badd39afee9073a2dc64d0581ae26;hpb=d629b7b5fe812f0040b83d27d2ada33b003aa918;p=dpdk.git diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst index 3b2b174ada..6dbbd5f8d1 100644 --- a/doc/guides/contributing/patches.rst +++ b/doc/guides/contributing/patches.rst @@ -28,13 +28,16 @@ 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. +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 `_ for further information. @@ -75,7 +78,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 @@ -86,7 +88,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. @@ -120,7 +121,8 @@ The proposer should justify the need for a new sub-tree and should have demonstr 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. @@ -132,12 +134,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 ----------------- @@ -148,9 +150,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. @@ -174,7 +186,7 @@ A good way of thinking about whether a patch should be split is to consider whet 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 then end of a +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. @@ -311,8 +323,8 @@ For example:: 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 `_ +All fix patches to the main 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:: @@ -328,6 +340,24 @@ In the commit message body the Cc: stable@dpdk.org should be inserted as follows For further information on stable contribution you can go to :doc:`Stable Contribution Guide `. +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 + --- + Depends-on: series-10000 ("Title of the series") Creating Patches ---------------- @@ -399,94 +429,76 @@ 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/ 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 -------------------- -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-linux-gcc+next+shared - -The script usage is:: - - test-build.sh [-h] [-jX] [-s] [config1 [config2] ...]] - -Where: - -* ``-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. - -Examples of configs are:: - - x86_64-native-linux-gcc - x86_64-native-linux-gcc+next+shared - x86_64-native-linux-clang+shared +Compilation of patches is to be tested with ``devtools/test-meson-builds.sh`` script. -The builds can be modified via the following environmental variables: +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. -* ``DPDK_BUILD_TEST_CONFIGS`` (target1+option1+option2 target2) -* ``DPDK_DEP_CFLAGS`` -* ``DPDK_DEP_LDFLAGS`` -* ``DPDK_DEP_PCAP`` (y/[n]) -* ``DPDK_NOTIFY`` (notify-send) -These can be set from the command line or in the config files shown above in the :ref:`contrib_checkpatch`. +.. _integrated_abi_check: -The recommended configurations and options to test compilation prior to submitting patches are:: +Checking ABI compatibility +-------------------------- - x86_64-native-linux-gcc+shared+next - x86_64-native-linux-clang+shared - i686-native-linux-gcc +By default, ABI compatibility checks are disabled. - export DPDK_DEP_ZLIB=y - export DPDK_DEP_PCAP=y - export DPDK_DEP_SSL=y +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``. -Meson System -~~~~~~~~~~~~ +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. -Compilation of patches is to be tested with ``devtools/test-meson-builds.sh`` script. +Sample:: -The script internally checks for dependencies, then builds for several -combinations of compilation configuration. + DPDK_ABI_REF_VERSION=v19.11 DPDK_ABI_REF_DIR=/tmp ./devtools/test-meson-builds.sh Sending Patches @@ -524,7 +536,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. @@ -648,12 +660,3 @@ patch accepted. The general cycle for patch review and acceptance is: than rework of the original. * Trivial patches may be merged sooner than described above at the tree committer's discretion. - -DPDK Maintainers ----------------- - -The following are the DPDK maintainers as listed in the ``MAINTAINERS`` file -in the DPDK root directory. - -.. literalinclude:: ../../../MAINTAINERS - :lines: 3-