X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fpatches.rst;h=214030346489c2a6562c5ab7fe0f73df3508d7ec;hb=a46987cf94997a4946dda186c811c6aa0ff894ab;hp=e4e0cb59159f4416ed767a1dc3e3389776a421c1;hpb=6561392c617a9bbc256c0ebe74b036441fed97da;p=dpdk.git diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst index e4e0cb5915..2140303464 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,9 +28,13 @@ 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. @@ -68,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 @@ -79,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. @@ -127,7 +132,7 @@ main repository:: git clone git://dpdk.org/dpdk git clone http://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-* @@ -141,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. @@ -166,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 then 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. @@ -278,7 +298,7 @@ in the body of the commit message. For example:: Signed-off-by: Alex Smith -`Bugzilla `_ +`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. @@ -300,7 +320,7 @@ 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 `_ +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:: @@ -423,10 +443,13 @@ Where the range is a ``git log`` option. 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-linuxapp-gcc+next+shared + devtools/test-build.sh x86_64-native-linux-gcc+next+shared The script usage is:: @@ -441,9 +464,9 @@ 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: @@ -457,14 +480,22 @@ 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. + Sending Patches --------------- @@ -501,7 +532,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. @@ -625,12 +656,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-