[PATCH 00/11] doc: improve contributing documentation clarity and style

[PATCH 00/11] doc: improve contributing documentation clarity and style

[Stephen Hemminger]

This patch series improves the readability and consistency of the DPDK
contributing documentation. The changes focus on editorial improvements
without altering any technical content or policies.

Initial work on this was done by the tech writer (Nandini)
but this is follow up using AI to get broader coverage.

The primary improvements across this series include:

- Converting passive voice to active voice for clearer, more direct prose
- Using imperative mood for guidelines and instructions
- Removing redundant phrases ("Please note that", "It is recommended that", etc.)
- Simplifying wordy constructions
- Fixing grammar, punctuation, and typos
- Improving consistency in terminology

The first patch fixes specific issues in the design guide, including
correcting "executive environment" to "execution environment" throughout.
The remaining patches systematically improve each contributing guide
document.

These changes make the documentation more accessible to new contributors
and align with modern technical writing best practices.

Stephen Hemminger (11):
  doc: correct grammar and typos in design guide
  doc: improve ABI policy documentation style
  doc: improve coding style guide readability
  doc: improve documentation guidelines style
  doc: improve Linux uAPI header documentation
  doc: improve new driver guide readability
  doc: improve new library guide style
  doc: improve patch submission guide readability
  doc: improve stable releases documentation
  doc: improve unit test guide readability
  doc: improve vulnerability process documentation

 doc/guides/contributing/abi_policy.rst    | 194 +++++-----
 doc/guides/contributing/coding_style.rst  |  20 +-
 doc/guides/contributing/design.rst        |  71 ++--
 doc/guides/contributing/documentation.rst |   6 +-
 doc/guides/contributing/linux_uapi.rst    |  40 +-
 doc/guides/contributing/new_driver.rst    |  62 ++--
 doc/guides/contributing/new_library.rst   |  20 +-
 doc/guides/contributing/patches.rst       | 434 +++++++++++-----------
 doc/guides/contributing/stable.rst        | 147 +++-----
 doc/guides/contributing/unit_test.rst     | 113 +++---
 doc/guides/contributing/vulnerability.rst | 140 ++++---
 11 files changed, 609 insertions(+), 638 deletions(-)

-- 
2.51.0

[PATCH 01/11] doc: correct grammar and typos in design guide

[Stephen Hemminger]

Changes:
- Use "execution environment" consistently (not "executive environment")
- Fix FreeBSD capitalization
- Use plural "these execution environments" to match multiple options
- Add hyphen to "non-exhaustive"
- Add missing comma before *telemetry*
- Remove double space
- Minor rewording for clarity

Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/design.rst | 71 ++++++++++++++++--------------
 1 file changed, 39 insertions(+), 32 deletions(-)

diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst
index 5517613424..a966da2ddd 100644
--- a/doc/guides/contributing/design.rst
+++ b/doc/guides/contributing/design.rst
@@ -1,6 +1,7 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright 2018 The DPDK contributors
 
+
 Design
 ======
 
@@ -8,22 +9,26 @@ Design
 Environment or Architecture-specific Sources
 --------------------------------------------
 
-In DPDK and DPDK applications, some code is specific to an architecture (i686, x86_64) or to an executive environment (freebsd or linux) and so on.
-As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL.
+In DPDK and DPDK applications, some code is architecture-specific (i686, x86_64) or environment-specific (FreeBSD or Linux, etc.).
+When feasible, such instances of architecture or env-specific code should be provided via standard APIs in the EAL.
+
+By convention, a file is specific if the directory is indicated. Otherwise, it is common.
+
+For example:
 
-By convention, a file is common if it is not located in a directory indicating that it is specific.
-For instance, a file located in a subdir of "x86_64" directory is specific to this architecture.
+A file located in a subdir of "x86_64" directory is specific to this architecture.
 A file located in a subdir of "linux" is specific to this execution environment.
 
 .. note::
 
    Code in DPDK libraries and applications should be generic.
-   The correct location for architecture or executive environment specific code is in the EAL.
+   The correct location for architecture or execution environment-specific code is in the EAL.
 
-When absolutely necessary, there are several ways to handle specific code:
+When necessary, there are several ways to handle specific code:
+
+
+* When the differences are small and they can be embedded in the same C file, use a ``#ifdef`` with a build definition macro in the C code.
 
-* Use a ``#ifdef`` with a build definition macro in the C code.
-  This can be done when the differences are small and they can be embedded in the same C file:
 
   .. code-block:: c
 
@@ -33,9 +38,9 @@ When absolutely necessary, there are several ways to handle specific code:
      titi();
      #endif
 
-* Use build definition macros and conditions in the Meson build file. This is done when the differences are more significant.
-  In this case, the code is split into two separate files that are architecture or environment specific.
-  This should only apply inside the EAL library.
+
+* When the differences are more significant, use build definition macros and conditions in the Meson build file. In this case, the code is split into two separate files that are architecture or environment specific. This should only apply inside the EAL library.
+
 
 Per Architecture Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -43,15 +48,16 @@ Per Architecture Sources
 The following macro options can be used:
 
 * ``RTE_ARCH`` is a string that contains the name of the architecture.
-* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_X32``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_RISCV``, ``RTE_ARCH_LOONGARCH``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` are defined only if we are building for those architectures.
+* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_X32``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_RISCV``, ``RTE_ARCH_LOONGARCH``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` are defined when building for these architectures.
+
 
 Per Execution Environment Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following macro options can be used:
 
-* ``RTE_EXEC_ENV_NAME`` is a string that contains the name of the executive environment.
-* ``RTE_EXEC_ENV_FREEBSD``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` are defined only if we are building for this execution environment.
+* ``RTE_EXEC_ENV_NAME`` is a string that contains the name of the execution environment.
+* ``RTE_EXEC_ENV_FREEBSD``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` are defined only if we are building for these execution environments.
 
 Mbuf features
 -------------
@@ -66,7 +72,7 @@ The "dynamic" area is eating the remaining space in mbuf,
 and some existing "static" fields may need to become "dynamic".
 
 Adding a new static field or flag must be an exception matching many criteria
-like (non exhaustive): wide usage, performance, size.
+like (non-exhaustive): wide usage, performance, size.
 
 
 Runtime Information - Logging, Tracing and Telemetry
@@ -82,11 +88,11 @@ DPDK provides a number of built-in mechanisms to provide this introspection:
 
 Each of these has its own strengths and suitabilities for use within DPDK components.
 
-Below are some guidelines for when each should be used:
+Here are guidelines for when each mechanism should be used:
 
 * For reporting error conditions, or other abnormal runtime issues, *logging* should be used.
-  Depending on the severity of the issue, the appropriate log level, for example,
-  ``ERROR``, ``WARNING`` or ``NOTICE``, should be used.
+  For example, depending on the severity of the issue, the appropriate log level,
+  ``ERROR``, ``WARNING`` or ``NOTICE`` should be used.
 
 .. note::
 
@@ -96,24 +102,24 @@ Below are some guidelines for when each should be used:
 
 * For component initialization, or other cases where a path through the code
   is only likely to be taken once,
-  either *logging* at ``DEBUG`` level or *tracing* may be used, or potentially both.
+  either *logging* at ``DEBUG`` level or *tracing* may be used, or both.
   In the latter case, tracing can provide basic information as to the code path taken,
   with debug-level logging providing additional details on internal state,
-  not possible to emit via tracing.
+  which is not possible to emit via tracing.
 
 * For a component's data-path, where a path is to be taken multiple times within a short timeframe,
   *tracing* should be used.
   Since DPDK tracing uses `Common Trace Format <https://diamon.org/ctf/>`_ for its tracing logs,
   post-analysis can be done using a range of external tools.
 
-* For numerical or statistical data generated by a component, for example, per-packet statistics,
+* For numerical or statistical data generated by a component, such as per-packet statistics,
   *telemetry* should be used.
 
-* For any data where the data may need to be gathered at any point in the execution
-  to help assess the state of the application component,
-  for example, core configuration, device information, *telemetry* should be used.
+* For any data that may need to be gathered at any point during the execution
+  to help assess the state of the application component (for example, core configuration, device information), *telemetry* should be used.
   Telemetry callbacks should not modify any program state, but be "read-only".
 
+
 Many libraries also include a ``rte_<libname>_dump()`` function as part of their API,
 writing verbose internal details to a given file-handle.
 New libraries are encouraged to provide such functions where it makes sense to do so,
@@ -135,13 +141,12 @@ requirements for preventing ABI changes when implementing statistics.
 Mechanism to allow the application to turn library statistics on and off
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Having runtime support for enabling/disabling library statistics is recommended,
-as build-time options should be avoided. However, if build-time options are used,
-for example as in the table library, the options can be set using c_args.
-When this flag is set, all the counters supported by current library are
+Having runtime support for enabling/disabling library statistics is recommended
+as build-time options should be avoided. However, if build-time options are used, as in the table library, the options can be set using c_args.
+When this flag is set, all the counters supported by the current library are
 collected for all the instances of every object type provided by the library.
 When this flag is cleared, none of the counters supported by the current library
-are collected for any instance of any object type provided by the library:
+are collected for any instance of any object type provided by the library.
 
 
 Prevention of ABI changes due to library statistics support
@@ -165,8 +170,8 @@ Motivation to allow the application to turn library statistics on and off
 
 It is highly recommended that each library provides statistics counters to allow
 an application to monitor the library-level run-time events. Typical counters
-are: number of packets received/dropped/transmitted, number of buffers
-allocated/freed, number of occurrences for specific events, etc.
+are: the number of packets received/dropped/transmitted, the number of buffers
+allocated/freed, the number of occurrences for specific events, etc.
 
 However, the resources consumed for library-level statistics counter collection
 have to be spent out of the application budget and the counters collected by
@@ -198,6 +203,7 @@ applications:
   the application may decide to turn the collection of statistics counters off for
   Library X and on for Library Y.
 
+
 The statistics collection consumes a certain amount of CPU resources (cycles,
 cache bandwidth, memory bandwidth, etc) that depends on:
 
@@ -218,6 +224,7 @@ cache bandwidth, memory bandwidth, etc) that depends on:
   validated for header integrity, counting the number of bits set in a bitmask
   might be needed.
 
+
 PF and VF Considerations
 ------------------------
 
@@ -229,5 +236,5 @@ Developers should work with the Linux Kernel community to get the required
 functionality upstream. PF functionality should only be added to DPDK for
 testing and prototyping purposes while the kernel work is ongoing. It should
 also be marked with an "EXPERIMENTAL" tag. If the functionality isn't
-upstreamable then a case can be made to maintain the PF functionality in DPDK
+upstreamable, then a case can be made to maintain the PF functionality in DPDK
 without the EXPERIMENTAL tag.
-- 
2.51.0

[PATCH 02/11] doc: improve ABI policy documentation style

[Stephen Hemminger]

Improve readability of the ABI policy documentation
- Converting passive voice to active voice
- Removing redundant phrases like "Please note that" and "Note that"
- Simplifying wordy constructions
- Using imperative mood for guidelines
- Fixing punctuation and grammar issues

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/abi_policy.rst | 194 ++++++++++++-------------
 1 file changed, 96 insertions(+), 98 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index f03a7467ac..2d1c17963d 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -7,7 +7,7 @@ ABI Policy
 Description
 -----------
 
-This document details the management policy that ensures the long-term stability
+This document details the management policy for ensuring long-term stability
 of the DPDK ABI and API.
 
 General Guidelines
@@ -16,28 +16,27 @@ General Guidelines
 #. Major ABI versions are declared no more frequently than yearly. Compatibility
    with the major ABI version is mandatory in subsequent releases until a
    :ref:`new major ABI version <new_abi_version>` is declared.
-#. Major ABI versions are usually but not always declared aligned with a
+#. Major ABI versions usually, but not always, align with a
    :ref:`LTS release <stable_lts_releases>`.
-#. The ABI version is managed at a project level in DPDK, and is reflected in
-   all non-experimental :ref:`library's soname <what_is_soname>`.
-#. The ABI should be preserved and not changed lightly. ABI changes must follow
+#. DPDK manages the ABI version at a project level, reflecting it
+   in all non-experimental :ref:`library sonames <what_is_soname>`.
+#. Preserve the ABI and avoid changing it lightly. ABI changes must follow
    the outlined :ref:`deprecation process <abi_changes>`.
-#. The addition of symbols is generally not problematic. The modification of
-   symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
-#. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
-   once approved these will form part of the next ABI version.
+#. Adding symbols is generally not problematic. Manage modification of
+   symbols with :ref:`ABI Versioning <abi_versioning>`.
+#. Removing symbols is considered an :ref:`ABI breakage <abi_breakages>`;
+   once approved, these removals form part of the next ABI version.
 #. Libraries or APIs marked as :ref:`experimental <experimental_apis>`
    may be changed or removed without prior notice,
    as they are not considered part of an ABI version.
    The :ref:`experimental <experimental_apis>` status of an API
    is not an indefinite state.
-#. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
-   support for hardware which was previously supported, should be treated as an
-   ABI change.
+#. Treat updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
+   support for previously supported hardware, as an ABI change.
 
 .. note::
 
-   Please note that this policy does not currently apply to the
+   This policy does not currently apply to the
    :doc:`Windows build <../windows_gsg/intro>`.
 
 What is an ABI?
@@ -45,13 +44,12 @@ What is an ABI?
 
 An ABI (Application Binary Interface) is the set of runtime interfaces exposed
 by a library. It is similar to an API (Application Programming Interface) but
-is the result of compilation.  It is also effectively cloned when applications
-link to dynamic libraries.  That is to say when an application is compiled to
-link against dynamic libraries, it is assumed that the ABI remains constant
-between the time the application is compiled/linked, and the time that it runs.
-Therefore, in the case of dynamic linking, it is critical that an ABI is
-preserved, or (when modified), done in such a way that the application is unable
-to behave improperly or in an unexpected fashion.
+is the result of compilation. Applications effectively clone the ABI when
+linking to dynamic libraries. When an application compiles and links against
+dynamic libraries, the ABI must remain constant between compile/link time
+and runtime. Therefore, in the case of dynamic linking, it is critical to
+preserve the ABI, or (when modifying it) to do so in a way that prevents
+the application from behaving improperly or unexpectedly.
 
 .. _figure_what_is_an_abi:
 
@@ -64,12 +62,12 @@ What is an ABI version?
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 An ABI version is an instance of a library's ABI at a specific release. Certain
-releases are considered to be milestone releases, the yearly LTS release for
+releases are considered milestone releases, the yearly LTS release for
 example. The ABI of a milestone release may be declared as a 'major ABI
 version', where this ABI version is then supported for some number of subsequent
 releases and is annotated in the library's :ref:`soname<what_is_soname>`.
 
-ABI version support in subsequent releases facilitates application upgrades, by
+ABI version support in subsequent releases facilitates application upgrades by
 enabling applications built against the milestone release to upgrade to
 subsequent releases of a library without a rebuild.
 
@@ -80,14 +78,14 @@ The DPDK ABI policy
 -------------------
 
 A new major ABI version is declared no more frequently than yearly, with
-declarations usually aligning with a LTS release, e.g. ABI 21 for DPDK 20.11.
+declarations usually aligning with an LTS release, e.g., ABI 21 for DPDK 20.11.
 Compatibility with the major ABI version is then mandatory in subsequent
-releases until the next major ABI version is declared, e.g. ABI 22 for DPDK
+releases until the next major ABI version is declared, e.g., ABI 22 for DPDK
 21.11.
 
 At the declaration of a major ABI version, major version numbers encoded in
 libraries' sonames are bumped to indicate the new version, with the minor
-version reset to ``0``. An example would be ``librte_eal.so.21.3`` would become
+version reset to ``0``. For example, ``librte_eal.so.21.3`` becomes
 ``librte_eal.so.22.0``.
 
 The ABI may then change multiple times, without warning, between the last major
@@ -96,12 +94,12 @@ that ABI compatibility with the major ABI version is preserved and therefore
 sonames do not change.
 
 Minor versions are incremented to indicate the release of a new ABI compatible
-DPDK release, typically the DPDK quarterly releases. An example of this, might
-be that ``librte_eal.so.21.1`` would indicate the first ABI compatible DPDK
-release, following the declaration of the new major ABI version ``21``.
+DPDK release, typically the DPDK quarterly releases. For example,
+``librte_eal.so.21.1`` indicates the first ABI compatible DPDK
+release following the declaration of the new major ABI version ``21``.
 
 An ABI version is supported in all new releases until the next major ABI version
-is declared. When changing the major ABI version, the release notes will detail
+is declared. When changing the major ABI version, the release notes detail
 all ABI changes.
 
 .. _figure_abi_stability_policy:
@@ -116,37 +114,37 @@ all ABI changes.
 ABI Changes
 ~~~~~~~~~~~
 
-The ABI may still change after the declaration of a major ABI version, that is
-new APIs may be still added or existing APIs may be modified.
+The ABI may still change after declaring a major ABI version—new APIs may be
+added or existing APIs modified.
 
 .. Warning::
 
-   Note that, this policy details the method by which the ABI may be changed,
+   This policy details the method by which the ABI may be changed,
    with due regard to preserving compatibility and observing deprecation
-   notices. This process however should not be undertaken lightly, as a general
-   rule ABI stability is extremely important for downstream consumers of DPDK.
-   The API should only be changed for significant reasons, such as performance
-   enhancements. API breakages due to changes such as reorganizing public
-   structure fields for aesthetic or readability purposes should be avoided.
+   notices. However, do not undertake this process lightly; as a general
+   rule, ABI stability is extremely important for downstream consumers of DPDK.
+   Change the API only for significant reasons, such as performance
+   enhancements. Avoid API breakages due to changes such as reorganizing public
+   structure fields for aesthetic or readability purposes.
 
 The requirements for changing the ABI are:
 
 #. At least 3 acknowledgments of the need to do so must be made on the
    dpdk.org mailing list.
 
-   - The acknowledgment of the maintainer of the component is mandatory, or if
+   - The component maintainer must acknowledge the change, or if
      no maintainer is available for the component, the tree/sub-tree maintainer
      for that component must acknowledge the ABI change instead.
 
-   - The acknowledgment of three members of the technical board, as delegates
-     of the `technical board <https://core.dpdk.org/techboard/>`_ acknowledging
-     the need for the ABI change, is also mandatory.
+   - Three members of the technical board, as delegates
+     of the `technical board <https://core.dpdk.org/techboard/>`_, must also
+     acknowledge the need for the ABI change.
 
-   - It is also recommended that acknowledgments from different "areas of
-     interest" be sought for each deprecation, for example: from NIC vendors,
+   - Seek acknowledgments from different "areas of
+     interest" for each deprecation, for example: from NIC vendors,
      CPU vendors, end-users, etc.
 
-#. Backward compatibility with the major ABI version must be maintained through
+#. Maintain backward compatibility with the major ABI version through
    :ref:`abi_versioning`, with :ref:`forward-only <forward-only>` compatibility
    offered for any ABI changes that are indicated to be part of the next ABI
    version.
@@ -159,7 +157,7 @@ The requirements for changing the ABI are:
      and Libraries <experimental_apis>`.
 
    - In situations in which an ``experimental`` symbol has been stable for some
-     time. When promoting the symbol to become part of the next ABI version, the
+     time, when promoting the symbol to become part of the next ABI version, the
      maintainer may choose to provide an alias to the ``experimental`` tag, so
      as not to break consuming applications.
 
@@ -167,56 +165,56 @@ The requirements for changing the ABI are:
    API becomes non-experimental, then the old one is marked with
    ``__rte_deprecated``.
 
-    - The deprecated API should follow the notification process to be removed,
-      see  :ref:`deprecation_notices`.
+    - The deprecated API should follow the notification process to be removed;
+      see :ref:`deprecation_notices`.
 
     - At the declaration of the next major ABI version, those ABI changes then
       become a formal part of the new ABI and the requirement to preserve ABI
-      compatibility with the last major ABI version is then dropped.
+      compatibility with the last major ABI version is dropped.
 
-    - The responsibility for removing redundant ABI compatibility code rests
-      with the original contributor of the ABI changes, failing that, then with
-      the contributor's company and then finally with the maintainer.
+    - The original contributor of the ABI changes is responsible for removing
+      redundant ABI compatibility code; failing that, the contributor's company,
+      and then finally the maintainer.
 
 .. _forward-only:
 
 .. Note::
 
-   Note that forward-only compatibility is offered for those changes made
+   Forward-only compatibility is offered for changes made
    between major ABI versions. As a library's soname can only describe
    compatibility with the last major ABI version, until the next major ABI
-   version is declared, these changes therefore cannot be resolved as a runtime
-   dependency through the soname. Therefore any application wishing to make use
-   of these ABI changes can only ensure that its runtime dependencies are met
+   version is declared, these changes cannot be resolved as a runtime
+   dependency through the soname. Therefore, any application wishing to use
+   these ABI changes can only ensure that its runtime dependencies are met
    through Operating System package versioning.
 
 .. _hw_rqmts:
 
 .. Note::
 
-   Updates to the minimum hardware requirements, which drop support for hardware
-   which was previously supported, should be treated as an ABI change, and
+   Treat updates to the minimum hardware requirements, which drop support for
+   previously supported hardware, as an ABI change, and
    follow the relevant deprecation policy procedures as above: 3 acks, technical
-   board approval and announcement at least one release in advance.
+   board approval, and announcement at least one release in advance.
 
 .. _abi_breakages:
 
 ABI Breakages
 ~~~~~~~~~~~~~
 
-For those ABI changes that are too significant to reasonably maintain multiple
-symbol versions, there is an amended process. In these cases, ABIs may be
-updated without the requirement of backward compatibility being provided. These
-changes must follow the same process :ref:`described above <abi_changes>` as non-breaking
-changes, however with the following additional requirements:
+An amended process exists for ABI changes too significant to reasonably maintain
+multiple symbol versions. In these cases, ABIs may be updated without providing
+backward compatibility. These changes must follow the same process
+:ref:`described above <abi_changes>` as non-breaking changes, with the following
+additional requirements:
 
 #. ABI breaking changes (including an alternative map file) can be included with
-   deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option, to provide
-   more details about oncoming changes. ``RTE_NEXT_ABI`` wrapper will be removed
+   the deprecation notice, wrapped by the ``RTE_NEXT_ABI`` option, to provide
+   more details about upcoming changes. The ``RTE_NEXT_ABI`` wrapper is removed
    at the declaration of the next major ABI version.
 
-#. Once approved, and after the deprecation notice has been observed these
-   changes will form part of the next declared major ABI version.
+#. Once approved, and after the deprecation notice has been observed, these
+   changes form part of the next declared major ABI version.
 
 Examples of ABI Changes
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -224,7 +222,7 @@ Examples of ABI Changes
 The following are examples of allowable ABI changes occurring between
 declarations of major ABI versions.
 
-* DPDK 20.11 release defines the function ``rte_foo()`` ; ``rte_foo()``
+* DPDK 20.11 release defines the function ``rte_foo()``; ``rte_foo()``
   is part of the major ABI version ``21``.
 
 * DPDK 21.02 release defines a new function ``rte_foo(uint8_t bar)``.
@@ -235,23 +233,23 @@ declarations of major ABI versions.
     number of releases, as described in the section :ref:`experimental_apis`.
 
   - Once ``rte_foo(uint8_t bar)`` becomes non-experimental, ``rte_foo()`` is
-    declared as ``__rte_deprecated`` and an deprecation notice is provided.
+    declared as ``__rte_deprecated`` and a deprecation notice is provided.
 
-* DPDK 20.11 is not re-released to include ``rte_foo(uint8_t bar)``, the new
+* DPDK 20.11 is not re-released to include ``rte_foo(uint8_t bar)``; the new
   version of ``rte_foo`` only exists from DPDK 21.02 onwards as described in the
   :ref:`note on forward-only compatibility<forward-only>`.
 
 * DPDK 21.02 release defines the experimental function ``__rte_experimental
   rte_baz()``. This function may or may not exist in the DPDK 21.05 release.
 
-* An application ``dPacket`` wishes to use ``rte_foo(uint8_t bar)``, before the
+* An application ``dPacket`` wishes to use ``rte_foo(uint8_t bar)`` before the
   declaration of the DPDK ``22`` major ABI version. The application can only
   ensure its runtime dependencies are met by specifying ``DPDK (>= 21.2)`` as
   an explicit package dependency, as the soname can only indicate the
   supported major ABI version.
 
 * At the release of DPDK 21.11, the function ``rte_foo(uint8_t bar)`` becomes
-  formally part of then new major ABI version DPDK ``22`` and ``rte_foo()`` may be
+  formally part of the new major ABI version DPDK ``22`` and ``rte_foo()`` may be
   removed.
 
 .. _deprecation_notices:
@@ -259,19 +257,19 @@ declarations of major ABI versions.
 Examples of Deprecation Notices
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following are some examples of ABI deprecation notices which would be
-added to the Release Notes:
+The following are some examples of ABI deprecation notices to add
+to the Release Notes:
 
 * The Macro ``#RTE_FOO`` is deprecated and will be removed with ABI version
   22, to be replaced with the inline function ``rte_foo()``.
 
 * The function ``rte_mbuf_grok()`` has been updated to include a new parameter
-  in version 21.2. Backwards compatibility will be maintained for this function
+  in version 21.2. Backward compatibility will be maintained for this function
   until the release of the new DPDK major ABI version 22, in DPDK version
   21.11.
 
 * The members of ``struct rte_foo`` have been reorganized in DPDK 21.02 for
-  performance reasons. Existing binary applications will have backwards
+  performance reasons. Existing binary applications will have backward
   compatibility in release 21.02, while newly built binaries will need to
   reference the new structure variant ``struct rte_foo2``. Compatibility will be
   removed in release 21.11, and all applications will require updating and
@@ -280,7 +278,7 @@ added to the Release Notes:
 
 * Significant ABI changes are planned for the ``librte_dostuff`` library. The
   upcoming release 21.02 will not contain these changes, but release 21.11 will,
-  and no backwards compatibility is planned due to the extensive nature of
+  and no backward compatibility is planned due to the extensive nature of
   these changes. Binaries using this library built prior to ABI version 22 will
   require updating and recompilation.
 
@@ -297,11 +295,11 @@ This is commonly known as the *ABI breakage window*,
 and some amended rules apply during this cycle:
 
  * The requirement to preserve compatibility with the previous major ABI
-   version, as described in the section :ref:`abi_changes` does not apply.
- * Contributors of compatibility preserving code in previous releases,
+   version, as described in the section :ref:`abi_changes`, does not apply.
+ * Contributors of compatibility preserving code in previous releases
    are now required to remove this compatibility code,
    as described in the section :ref:`abi_changes`.
- * Symbol versioning references to the old ABI version are updated
+ * Update symbol versioning references to the old ABI version
    to reference the new ABI version,
    as described in the section :ref:`deprecating_entire_abi`.
  * Contributors of aliases to experimental in previous releases,
@@ -309,9 +307,9 @@ and some amended rules apply during this cycle:
    are now required to remove these aliases.
  * Finally, the *ABI breakage window* is *not* permission to circumvent
    the other aspects of the procedures to make ABI changes
-   described in :ref:`abi_changes`, that is, 3 ACKs of the requirement
+   described in :ref:`abi_changes`; that is, 3 ACKs of the requirement
    to break the ABI and the observance of a deprecation notice
-   are still considered mandatory.
+   are still mandatory.
 
 .. _experimental_apis:
 
@@ -324,31 +322,31 @@ APIs
 APIs marked as ``experimental`` are not considered part of an ABI version and
 may be changed or removed without prior notice. Since changes to APIs are most likely
 immediately after their introduction, as users begin to take advantage of those
-new APIs and start finding issues with them, new DPDK APIs will be automatically
+new APIs and start finding issues with them, new DPDK APIs are automatically
 marked as ``experimental`` to allow for a period of stabilization before they
 become part of a tracked ABI version.
 
-Note that marking an API as experimental is a multi step process.
-To mark an API as experimental, the symbols which are desired to be exported
-must be annotated with a RTE_EXPORT_EXPERIMENTAL_SYMBOL call in the corresponding libraries'
+Note that marking an API as experimental is a multi-step process.
+To mark an API as experimental, annotate the symbols to be exported
+with a RTE_EXPORT_EXPERIMENTAL_SYMBOL call in the corresponding libraries'
 sources.
-Experimental symbols must be commented so that it is clear in which DPDK
+Comment experimental symbols so that it is clear in which DPDK
 version they were introduced.
 
-Secondly, the corresponding prototypes of those exported functions (in the
-development header files), must be marked with the ``__rte_experimental`` tag
+Secondly, mark the corresponding prototypes of those exported functions (in the
+development header files) with the ``__rte_experimental`` tag
 (see ``rte_compat.h``).
 
 In addition to tagging the code with ``__rte_experimental``,
 the doxygen markup must also contain the EXPERIMENTAL string,
 and the MAINTAINERS file should note the EXPERIMENTAL libraries.
 
-For removing the experimental tag associated with an API, deprecation notice is
-not required. Though, an API should remain in experimental state for at least
-one release. Thereafter, the normal process of posting patch for review to
+For removing the experimental tag associated with an API, a deprecation notice is
+not required. However, an API should remain in experimental state for at least
+one release. Thereafter, the normal process of posting a patch for review to the
 mailing list can be followed.
 
-After the experimental tag has been formally removed, a tree/sub-tree maintainer
+After formally removing the experimental tag, a tree/sub-tree maintainer
 may choose to offer an alias to the experimental tag so as not to break
 applications using the symbol. The alias is then dropped at the declaration of
 next major ABI version.
@@ -363,16 +361,16 @@ All functions in such libraries may be changed or removed without prior notice.
 Promotion to stable
 ~~~~~~~~~~~~~~~~~~~
 
-An API's ``experimental`` status should be reviewed annually,
+Review an API's ``experimental`` status annually,
 by both the maintainer and/or the original contributor.
-Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
-once a maintainer has become satisfied that the API is mature
+Ordinarily, promote APIs marked as ``experimental`` to the stable ABI
+once a maintainer is satisfied that the API is mature
 and is unlikely to change.
 
 In exceptional circumstances, should an API still be classified
 as ``experimental`` after two years
-and is without any prospect of becoming part of the stable API.
-The API will then become a candidate for removal,
+and be without any prospect of becoming part of the stable API,
+the API will then become a candidate for removal,
 to avoid the accumulation of abandoned symbols.
 
 Should an ABI change, usually due to a direct change to the API's signature,
-- 
2.51.0

[PATCH 03/11] doc: improve coding style guide readability

[Stephen Hemminger]

Improve the coding style documentation
- Converting passive voice to active voice
- Using imperative mood for instructions
- Simplifying redundant phrasing
- Clarifying guidance on bool usage in structures

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/coding_style.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst
index 243a3c2959..898c84ceec 100644
--- a/doc/guides/contributing/coding_style.rst
+++ b/doc/guides/contributing/coding_style.rst
@@ -9,8 +9,8 @@ DPDK Coding Style
 Description
 -----------
 
-This document specifies the preferred style for source files in the DPDK source tree.
-It is based on the Linux Kernel coding guidelines and the FreeBSD 7.2 Kernel Developer's Manual (see man style(9)), but was heavily modified for the needs of the DPDK.
+This document specifies the preferred style for source files in the DPDK source tree,
+based on the Linux Kernel coding guidelines and the FreeBSD 7.2 Kernel Developer's Manual (see man style(9)), but was heavily modified for the needs of the DPDK.
 
 General Guidelines
 ------------------
@@ -95,7 +95,7 @@ Example:
 Header File Guards
 ~~~~~~~~~~~~~~~~~~
 
-Headers should be protected against multiple inclusion with the usual:
+Protect headers against multiple inclusion with the usual:
 
 .. code-block:: c
 
@@ -293,7 +293,7 @@ Structure Declarations
 * In general, when declaring variables in new structures, declare them sorted by use, then by size (largest to smallest), and then in alphabetical order.
   Sorting by use means that commonly used variables are used together and that the structure layout makes logical sense.
   Ordering by size then ensures that as little padding is added to the structure as possible.
-* For existing structures, additions to structures should be added to the end so for backward compatibility reasons.
+* For existing structures, add new members to the end for backward compatibility.
 * Each structure element gets its own line.
 * Try to make the structure readable by aligning the member names using spaces as shown below.
 * Names following extremely long types, which therefore cannot be easily aligned with the rest, should be separated by a single space.
@@ -308,14 +308,14 @@ Structure Declarations
  };
 
 
-* Major structures should be declared at the top of the file in which they are used, or in separate header files if they are used in multiple source files.
+* Declare major structures at the top of the file where they are used, or in separate header files if they are used in multiple source files.
 * Use of the structures should be by separate variable declarations and those declarations must be extern if they are declared in a header file.
 * Externally visible structure definitions should have the structure name prefixed by ``rte_`` to avoid namespace collisions.
 
 .. note::
 
-    Uses of ``bool`` in structures are not preferred as is wastes space and
-    it's also not clear as to what type size the bool is. A preferred use of
+    Avoid using ``bool`` in structures because it wastes space and
+    the type size is unclear. A preferred use of
     ``bool`` is mainly as a return type from functions that return true/false,
     and maybe local variable functions.
 
@@ -584,7 +584,7 @@ C Function Definition, Declaration and Use
 Prototypes
 ~~~~~~~~~~
 
-* It is recommended (and generally required by the compiler) that all non-static functions are prototyped somewhere.
+* Prototype all non-static functions (the compiler generally requires this).
 * Functions local to one source module should be declared static, and should not be prototyped unless absolutely necessary.
 * Functions used from other parts of code (external API) must be prototyped in the relevant include file.
 * Function prototypes should be listed in a logical order, preferably alphabetical unless there is a compelling reason to use a different ordering.
@@ -747,7 +747,7 @@ Static Variables and Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * All functions and variables that are local to a file must be declared as ``static`` because it can often help the compiler to do some optimizations (such as, inlining the code).
-* Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file.
+* Declare functions that should be inlined as ``static inline`` and can be defined in a .c or a .h file.
 
 .. note::
 	Static functions defined in a header file must be declared as ``static inline`` in order to prevent compiler warnings about the function being unused.
@@ -755,7 +755,7 @@ Static Variables and Functions
 Const Attribute
 ~~~~~~~~~~~~~~~
 
-The ``const`` attribute should be used as often as possible when a variable is read-only.
+Use the ``const`` attribute as often as possible when a variable is read-only.
 
 Inline ASM in C code
 ~~~~~~~~~~~~~~~~~~~~
-- 
2.51.0

[PATCH 04/11] doc: improve documentation guidelines style

[Stephen Hemminger]

Improve readability of the documentation guidelines
- Using active voice throughout
- Converting "should be" constructions to imperative mood
- Fixing minor grammar issues in Doxygen guidance

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/documentation.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 338254cf30..c6009cbc12 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -39,7 +39,7 @@ The main directories that contain files related to documentation are shown below
        |-- ...
 
 
-The API documentation is built from `Doxygen <http://www.doxygen.nl>`_ comments in the header files.
+Doxygen comments in header files generate the API documentation. These are built from `Doxygen <http://www.doxygen.nl>`_ comments in the header files.
 These files are mainly in the ``lib/*`` directories although some of the Poll Mode Drivers in ``drivers/net``
 are also documented with Doxygen.
 
@@ -84,7 +84,7 @@ added to by the developer.
   The API documentation explains how to use the public DPDK functions.
   The `API index page <https://doc.dpdk.org/api/>`_ shows the generated API documentation with related groups of functions.
 
-  The API documentation should be updated via Doxygen comments when new functions are added.
+  Update API documentation via Doxygen comments when adding new functions.
 
 * **Getting Started Guides**
 
@@ -606,7 +606,7 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati
   It isn't necessary to explicitly name each file since the configuration matches all ``rte_*.h`` files in the directory.
 
 * Use proper capitalization and punctuation in the Doxygen comments since they will become sentences in the documentation.
-  This in particular applies to single line comments, which is the case the is most often forgotten.
+  This applies particularly to single-line comments, which developers most often forget.
 
 * Use ``@`` style Doxygen commands instead of ``\`` style commands.
 
-- 
2.51.0

[PATCH 05/11] doc: improve Linux uAPI header documentation

[Stephen Hemminger]

Improve clarity of the Linux uAPI header documentation
- Converting passive voice to active voice
- Simplifying sentence structure
- Making instructions more direct
- Removing redundant wording

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/linux_uapi.rst | 40 ++++++++++++--------------
 1 file changed, 19 insertions(+), 21 deletions(-)

diff --git a/doc/guides/contributing/linux_uapi.rst b/doc/guides/contributing/linux_uapi.rst
index a1bc0ba604..b28ebc4663 100644
--- a/doc/guides/contributing/linux_uapi.rst
+++ b/doc/guides/contributing/linux_uapi.rst
@@ -7,36 +7,34 @@ Linux uAPI header files
 Rationale
 ---------
 
-The system a DPDK library or driver is built on is not necessarily running the
-same Kernel version than the system that will run it.
-Importing Linux Kernel uAPI headers enable to build features that are not
-supported yet by the build system.
+The build system may run a different kernel version than the deployment target.
+To support features unavailable in the build system's kernel, import Linux kernel uAPI headers.
 
-For example, the build system runs upstream Kernel v5.19 and we would like to
-build a VDUSE application that will use VDUSE_IOTLB_GET_INFO ioctl() introduced
-in Linux Kernel v6.0.
+For example, if the build system runs upstream Kernel v5.19, but you need to build a VDUSE application
+that uses the VDUSE_IOTLB_GET_INFO ioctl introduced in Kernel v6.0, importing the relevant uAPI headers enables this.
+
+The Linux kernel's syscall license exception permits the inclusion of unmodified uAPI header files in such cases.
 
 `Linux Kernel licence exception regarding syscalls
 <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/LICENSES/exceptions/Linux-syscall-note>`_
-enable importing unmodified Linux Kernel uAPI header files.
+enables importing unmodified Linux Kernel uAPI header files.
 
 Importing or updating an uAPI header file
 -----------------------------------------
 
-In order to ensure the imported uAPI headers are both unmodified and from a
-released version of the linux Kernel, a helper script is made available and
-MUST be used.
+To ensure that imported uAPI headers are unmodified and sourced from an official Linux
+kernel release, a helper script is provided and must be used.
 Below is an example to import ``linux/vduse.h`` file from Linux ``v6.10``:
 
 .. code-block:: console
 
    devtools/linux-uapi.sh -i linux/vduse.h -u v6.10
 
-Once imported, the header files should be committed without any other change.
-Note that all the imported headers will be updated to the requested version.
+Once imported, commit header files without any modifications. Note that all imported
+headers are updated to match the specified kernel version.
 
-Updating imported headers to a newer released version should only be done on
-a need basis, it can be achieved using the same script:
+Perform updates to a newer released version only when necessary, using
+the same helper script.
 
 .. code-block:: console
 
@@ -44,8 +42,8 @@ a need basis, it can be achieved using the same script:
 
 The commit message should reflect why updating the headers is necessary.
 
-Once committed, user can check headers are valid by using the same Linux
-uAPI script using the check option:
+Once committed, check that headers are valid using the same Linux
+uAPI script with the check option:
 
 .. code-block:: console
 
@@ -60,13 +58,13 @@ Note that all the linux-uapi.sh script options can be combined. For example:
 Header inclusion into library or driver
 ---------------------------------------
 
-The library or driver willing to make use of imported uAPI headers needs to
-explicitly include the header file with ``uapi/`` prefix in C files.
+Libraries or drivers that rely on imported uAPI headers must explicitly include
+the relevant header using the ``uapi/`` prefix in their C source files.
 
 This inclusion must be done before any header external to DPDK is included,
-to prevent inclusion of this system uAPI header in any of those external headers.
+to prevent inclusion of the system uAPI header in any of those external headers.
 
-For example to include VDUSE uAPI:
+For example, to include VDUSE uAPI:
 
 .. code-block:: c
 
-- 
2.51.0

[PATCH 06/11] doc: improve new driver guide readability

[Stephen Hemminger]

Improve the new driver contribution guide
- Converting passive voice to active voice
- Using imperative mood for recommendations
- Removing "We recommend" and similar phrases
- Simplifying wordy constructions

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/new_driver.rst | 62 +++++++++++++-------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/doc/guides/contributing/new_driver.rst b/doc/guides/contributing/new_driver.rst
index 555e875329..23d986d941 100644
--- a/doc/guides/contributing/new_driver.rst
+++ b/doc/guides/contributing/new_driver.rst
@@ -6,10 +6,10 @@ Adding a New Driver
 ===================
 
 The DPDK project continuously grows its ecosystem by adding support for new devices.
-This document is designed to assist contributors in creating DPDK drivers,
+This document assists contributors in creating DPDK drivers,
 also known as Poll Mode Drivers (PMD).
 
-By having public support for a device, we can ensure accessibility across various
+By having public support for a device, we ensure accessibility across various
 operating systems and guarantee community maintenance in future releases.
 If a new device is similar to a device already supported by an existing driver,
 it is more efficient to update the existing driver.
@@ -20,8 +20,8 @@ Here are our best practice recommendations for creating a new driver.
 Early Engagement with the Community
 -----------------------------------
 
-When creating a new driver, we highly recommend engaging with the DPDK
-community early instead of waiting the work to mature.
+When creating a new driver, engage with the DPDK community early
+rather than waiting for the work to mature.
 
 These public discussions help align development of your driver with DPDK expectations.
 You may submit a roadmap before the release to inform the community of your plans.
@@ -29,31 +29,31 @@ Additionally, sending a Request For Comments (RFC) early in the release cycle,
 or even during the prior release, is advisable.
 
 DPDK is mainly consumed via Long Term Support (LTS) releases.
-It is common to target a new PMD to a LTS release. For this,
-it is suggested to start upstreaming at least one release before a LTS release.
+It is common to target a new PMD to an LTS release. For this,
+start upstreaming at least one release before an LTS release.
 
 
 Progressive Work
 ----------------
 
-To continually progress your work, we recommend planning
+To continually progress your work, plan
 for incremental upstreaming across multiple patch series or releases.
 
-It's important to prioritize quality of the driver over upstreaming
+Prioritize quality of the driver over upstreaming
 in a single release or single patch series.
 
 
 Finalizing
 ----------
 
-Once the driver has been upstreamed,
-the author has a responsibility to the community to maintain it.
+Once the driver is upstreamed,
+the author is responsible for maintaining it.
 
 This includes the public test report.
 Authors must send a public test report after the first upstreaming of the PMD.
 The same public test procedure may be reproduced regularly per release.
 
-After the PMD is upstreamed, the author should send a patch to update
+After the PMD is upstreamed, send a patch to update
 `the website <https://core.dpdk.org/supported/>`_
 with the name of the new PMD and supported devices via the
 `DPDK web mailing list <https://mails.dpdk.org/listinfo/web>`_.
@@ -64,7 +64,7 @@ For more information about the role of maintainers, see :doc:`patches`.
 Splitting into Patches
 ----------------------
 
-We recommend that drivers are split into patches,
+Split drivers into patches
 so that each patch represents a single feature.
 If the driver code is already developed, it may be challenging to split.
 However, there are many benefits to doing so.
@@ -73,17 +73,17 @@ Splitting patches makes it easier to understand a feature
 and clarifies the list of components/files that compose that specific feature.
 
 It also enables the ability to track
-from the source code to the feature it is enabled for,
-and helps users to understand the reasoning and intention of implementation.
+from the source code to the feature it enables,
+and helps users understand the reasoning and intention of implementation.
 This kind of tracing is regularly required for defect resolution and refactoring.
 
 Another benefit of splitting the codebase per feature is that
 it highlights unnecessary or irrelevant code,
 as any code not belonging to any specific feature becomes obvious.
 
-Git bisect is also more useful if patches are split per patch.
+Git bisect is also more useful if patches are split per feature.
 
-The split should focus on logical features rather than file-based divisions.
+Focus the split on logical features rather than file-based divisions.
 
 Each patch in the series must compile without errors
 and should maintain functionality.
@@ -92,20 +92,20 @@ Enable the build as early as possible within the series
 to facilitate continuous integration and testing.
 This approach ensures a clear and manageable development process.
 
-We suggest splitting patches following this approach:
+Split patches following this approach:
 
-* Each patch should be organized logically as a new feature.
+* Organize each patch logically as a new feature.
 * Run test tools per patch (See :ref:`tool_list`).
 * Update relevant documentation and `<driver>.ini` file with each patch.
 
-The following order in the patch series is as suggested below.
+The following order in the patch series is suggested.
 
 The first patch should have the driver's skeleton which should include:
 
 * Maintainers file update
 * Driver documentation
 * Document must have links to official product documentation web page
-* The new document should be added into the index (`index.rst`)
+* Add the new document to the index (`index.rst`)
 * Initial `<driver>.ini` file
 * Release notes announcement for the new driver
 
@@ -152,10 +152,10 @@ Time synchronization, PTP
 Performance documentation
 ================================  ================================
 
-After all features are enabled,
+After enabling all features,
 if there is remaining base code that is not upstreamed,
-they can be upstreamed at the end of the patch series.
-However, we recommend these patches are still split into logical groups.
+upstream it at the end of the patch series.
+However, still split these patches into logical groups.
 
 
 Additional Suggestions
@@ -185,12 +185,12 @@ Remember to do the following:
 Dependencies
 ------------
 
-At times, drivers may have dependencies to external software.
-For driver dependencies, same DPDK rules for dependencies applies.
-Dependencies should be publicly and freely available,
-drivers which depend on non-available components will not be accepted.
+At times, drivers may have dependencies on external software.
+For driver dependencies, the same DPDK rules for dependencies apply.
+Dependencies should be publicly and freely available;
+drivers that depend on unavailable components will not be accepted.
 If the required dependency is not yet publicly available,
-then wait to submit the driver until the dependent library is available.
+wait to submit the driver until the dependent library is available.
 
 
 .. _tool_list:
@@ -199,10 +199,10 @@ Test Tools
 ----------
 
 Build and check the driver's documentation.
-Make sure there are no warnings,
-and driver shows up in the relevant index page.
+Ensure there are no warnings
+and the driver shows up in the relevant index page.
 
-Be sure to run the following test tools per patch in a patch series:
+Run the following test tools per patch in a patch series:
 
 * `checkpatches.sh`
 * `check-git-log.sh`
-- 
2.51.0

[PATCH 07/11] doc: improve new library guide style

[Stephen Hemminger]

Improve the new library contribution guide
- Converting passive voice to active voice
- Simplifying sentence structure
- Using more direct language

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/new_library.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/doc/guides/contributing/new_library.rst b/doc/guides/contributing/new_library.rst
index 99890beb29..25237b349f 100644
--- a/doc/guides/contributing/new_library.rst
+++ b/doc/guides/contributing/new_library.rst
@@ -10,15 +10,15 @@ Process for approval in principle
 Rationale
 ~~~~~~~~~
 
-Adding a new library to DPDK with proper RFC and then full patch-sets is a significant work.
-In order to save effort, developers should get an early approval in principle,
-or an early feedback in case the library is not suitable for various reasons.
+Adding a new library to DPDK with proper RFC and then full patch-sets requires significant effort.
+To save effort, developers should seek early approval in principle,
+or early feedback if the library is unsuitable for various reasons.
 
 Process
 ~~~~~~~
 
-#. When a contributor would like to add a new library to DPDK code base,
-   the contributor must send the following items to DPDK mailing list
+#. When a contributor would like to add a new library to the DPDK code base,
+   the contributor must send the following items to the DPDK mailing list
    for Technical Board approval-in-principle.
 
    * Purpose of the library.
@@ -38,13 +38,13 @@ Process
 
    * Any new library dependencies to DPDK.
 
-#. Technical Board to schedule discussion on this in upcoming Technical Board meeting
-   along with author.
+#. Technical Board schedules discussion on this in an upcoming Technical Board meeting
+   along with the author.
    Based on the Technical Board schedule and/or author availability,
    Technical Board may need a maximum of **five** Technical Board meeting slots.
 
 #. Based on mailing list and Technical Board meeting discussions,
-   Technical Board to vote and share the decision in the mailing list.
+   Technical Board votes and shares the decision on the mailing list.
    The decision outcome can be any of the following:
 
    * Approved in principle
@@ -53,5 +53,5 @@ Process
 
 #. Once the Technical Board approves the library in principle,
    it is safe to start working on the implementation.
-   However, the patches will need to meet the usual quality criteria
-   in order to be effectively accepted.
+   However, the patches must meet the usual quality criteria
+   to be effectively accepted.
-- 
2.51.0

[PATCH 08/11] doc: improve patch submission guide readability

[Stephen Hemminger]

Improve the patch submission documentation
- Converting passive voice to active voice throughout
- Using imperative mood for instructions
- Reorganizing content with clearer section headers
- Simplifying wordy constructions
- Removing redundant phrases

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/patches.rst | 434 ++++++++++++++--------------
 1 file changed, 224 insertions(+), 210 deletions(-)

diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index 069a18e4ec..129952dc76 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -6,55 +6,53 @@
 Contributing Code to DPDK
 =========================
 
-This document outlines the guidelines for submitting code to DPDK.
+This document provides guidelines for submitting code to DPDK.
 
-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:
+The DPDK development process is loosely based on the Linux Kernel development
+model. Review the Linux kernel's guide:
 `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.
+Many of DPDK's submission guidelines draw from the kernel process,
+and the rationale behind them is often explained in greater depth there.
 
 
 The DPDK Development Process
 ----------------------------
 
-The DPDK development process has the following features:
+The DPDK development process includes the following key elements:
 
-* The code is hosted in a public git repository.
-* There is a mailing list where developers submit patches.
-* There are maintainers for hierarchical components.
-* Patches are reviewed publicly on the mailing list.
-* Successfully reviewed patches are merged to the repository.
-* Patches should be sent to the target repository or sub-tree, see below.
+* The project maintains code in a public Git repository.
+* Developers submit patches via a public mailing list.
+* A hierarchical structure assigns maintainers to different components.
+* The community reviews patches publicly on the mailing list.
+* Maintainers merge reviewed patches into the repository.
+* Contributors should send patches to the target repository or sub-tree (see below for details).
 
 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/>`_
+Contributors must `register for the mailing list <https://mails.dpdk.org/listinfo/dev>`_ to submit patches.
+Register for DPDK `Patchwork <https://patches.dpdk.org/project/dpdk/list/>`_ as well.
 
-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.
+If you use GitHub, pushing to a branch triggers GitHub Actions,
+which builds your changes and runs unit tests and ABI checks.
 
-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.
+Contributing to DPDK requires a basic understanding of the Git version control system.
+For more information, refer to the `Pro Git Book <http://www.git-scm.com/book/>`_.
 
 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 <http://spdx.org/>`_.
+DPDK uses the Open Source BSD-3-Clause license for its core libraries and
+drivers. Kernel components use the GPL-2.0 license.
+To identify licenses in source files, DPDK follows the SPDX standard
+developed by the Linux Foundation `SPDX project <http://spdx.org/>`_.
 
-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.
+Use the SPDX tag on the first line of the file.
+For *#!* scripts, place the SPDX tag on the second line.
 
-For example, to label a file as subject to the BSD-3-Clause license,
-the following text would be used:
+For BSD-3-Clause:
 
 ``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:
+For dual-licensing with BSD-3-Clause and GPL-2.0 (e.g., shared kernel/user-space code):
 
 ``SPDX-License-Identifier: (BSD-3-Clause OR GPL-2.0)``
 
@@ -63,11 +61,11 @@ Refer to ``licenses/README`` for more details.
 Maintainers and Sub-trees
 -------------------------
 
-The DPDK maintenance hierarchy is divided into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
+The DPDK maintenance hierarchy divides into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
 
-There are maintainers for the trees and for components within the tree.
+Maintainers exist for the trees and for components within the tree.
 
-Trees and maintainers are listed in the ``MAINTAINERS`` file. For example::
+The ``MAINTAINERS`` file lists trees and maintainers. For example::
 
     Crypto Drivers
     --------------
@@ -85,45 +83,49 @@ Where:
 * ``T`` is a repository tree.
 * ``F`` is a maintained file or directory.
 
-Additional details are given in the ``MAINTAINERS`` file.
+The ``MAINTAINERS`` file contains additional details.
 
-The role of the component maintainers is to:
+Component maintainers are responsible for:
 
-* Review patches for the component or delegate the review.
-  The review should be done, ideally, within 1 week of submission to the mailing list.
-* Add an ``acked-by`` to patches, or patchsets, that are ready for committing to a tree.
-* Reply to questions asked about the component.
+* Reviewing patches related to their component or delegating review to others.
+  Ideally, complete reviews within one week of mailing list submission.
+* Acknowledging patches by adding an ``acked-by`` tag to those deemed ready for merging.
+* Responding to questions regarding the component and offering guidance when needed.
 
-Component maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
-Maintainers should have demonstrated a reasonable level of contributions or reviews to the component area.
-The maintainer should be confirmed by an ``ack`` from an established contributor.
-There can be more than one component maintainer if desired.
+Add or remove maintainers by submitting a patch to the ``MAINTAINERS`` file.
+New maintainers should have demonstrated consistent contributions or reviews to the component area.
+An established contributor must confirm their addition with an ``ack``.
+A single component may have multiple maintainers if needed.
 
-The role of the tree maintainers is to:
+Tree Maintainer Responsibilities:
 
-* Maintain the overall quality of their tree.
-  This can entail additional review, compilation checks or other tests deemed necessary by the maintainer.
-* Commit patches that have been reviewed by component maintainers and/or other contributors.
-  The tree maintainer should determine if patches have been reviewed sufficiently.
-* Ensure that patches are reviewed in a timely manner.
-* Prepare the tree for integration.
-* Ensure that there is a designated back-up maintainer and coordinate a handover for periods where the
-  tree maintainer can't perform their role.
+Tree maintainers ensure the overall quality and integrity of their tree.
+Their duties include:
 
-Tree maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
-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.
-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.
+* Conducting additional reviews, compilation checks, or other tests as needed.
+* Committing patches that component maintainers or other contributors have sufficiently reviewed.
+* Ensuring timely review of submitted patches.
+* Preparing the tree for integration.
+* Appointing a designated backup maintainer and coordinating handovers when unavailable.
 
-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.
+Maintainer Changes:
+
+Add or remove tree maintainers by submitting a patch to the MAINTAINERS file.
+Proposals must justify the creation of a new sub-tree and demonstrate significant contribution
+to the relevant area. An existing tree maintainer must ack the proposal.
+
+Escalate disputes regarding trees or maintainers to the Technical Board.
+
+Backup Maintainers:
+
+* Choose the main tree's backup maintainer from among existing sub-tree maintainers.
+* Choose a sub-tree's backup from the component maintainers within that sub-tree.
 
 
 Getting the Source Code
 -----------------------
 
-The source code can be cloned using either of the following:
+Clone the source code using either of the following:
 
 main repository::
 
@@ -135,63 +137,72 @@ sub-repositories (`list <https://git.dpdk.org/next>`_)::
     git clone git://dpdk.org/next/dpdk-next-*
     git clone https://dpdk.org/git/next/dpdk-next-*
 
-Make your Changes
------------------
+Make Changes
+------------
 
-Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines and requirements:
+After cloning the DPDK repository, make your planned changes while following
+these key guidelines and requirements:
 
 * Follow the :ref:`coding_style` guidelines.
 
 * If you are a new contributor, or if your mail address changed,
   you may update the ``.mailmap`` file.
-  Otherwise the new name or address will be added by a maintainer.
-  Keeping this file up-to-date will help when someone wants to contact you
-  about the changes you contributed to.
+  Otherwise a maintainer will add the new name or address.
+  Keeping this file up-to-date helps when someone wants to contact you
+  about the changes you contributed.
+
+* If you add new files or directories, add your name to the ``MAINTAINERS`` file.
 
-* If you add new files or directories you should add your name to the ``MAINTAINERS`` file.
+PMD Submissions
+~~~~~~~~~~~~~~~
 
-* Initial submission of new PMDs should be prepared against a corresponding repo.
+* Prepare initial submissions of new PMDs against the corresponding repo.
 
-  * Thus, for example, initial submission of a new network PMD should be
-    prepared against dpdk-next-net repo.
+  * For example, prepare initial submission of a new network PMD
+    against the dpdk-next-net repo.
 
-  * Likewise, initial submission of a new crypto or compression PMD should be
-    prepared against dpdk-next-crypto repo.
+  * Likewise, prepare initial submission of a new crypto or compression PMD
+    against the dpdk-next-crypto repo.
 
   * For other PMDs and more info, refer to the ``MAINTAINERS`` file.
 
-* New external functions should be exported.
+* Export new external functions.
   See the :doc:`ABI policy <abi_policy>` and :ref:`ABI versioning <abi_versioning>`
   guides.
 
-* Any new API function should be used in ``/app`` test directory.
+API and ABI Guidelines
+~~~~~~~~~~~~~~~~~~~~~~
+
+* Use any new API function in the ``/app`` test directory.
 
 * When introducing a new device API, at least one driver should implement it.
 
-* Important changes will require an addition to the release notes in ``doc/guides/rel_notes/``.
+Documentation and Release Notes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Important changes 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.
 
-* Test the compilation works with different targets, compilers and options, see :ref:`contrib_check_compilation`.
+* Test compilation with different targets, compilers, and options; see :ref:`contrib_check_compilation`.
 
-* 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.
+* Do not break compilation between commits with forward dependencies in a patch set.
+  Each commit should compile on its own to allow ``git bisect`` and continuous integration testing.
 
 * 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>`.
 
-* Code and related documentation must be updated atomically in the same patch.
+* Update code and related documentation atomically in the same patch.
 
-Once the changes have been made you should commit them to your local repo.
+Commit your changes to your local repo after making them.
 
-For small changes, that do not require specific explanations, it is better to keep things together in the
-same patch.
-Larger changes that require different explanations should be separated into logical patches in a patchset.
-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.
+Keep small changes that do not require specific explanations in a single patch.
+Separate larger changes that require different explanations into logical patches in a patch set.
+Consider whether the change could be applied without dependencies as a backport
+when deciding whether to split a patch.
 
-As a guide to how patches should be structured run ``git log`` on similar files.
+Run ``git log`` on similar files as a guide to how patches should be structured.
 
 
 Commit Messages: Subject Line
@@ -206,7 +217,7 @@ Here are some guidelines for the summary line:
 
 * The summary line should be lowercase apart from acronyms.
 
-* It should be prefixed with the component name (use git log to check existing components).
+* Prefix with the component name (use git log to check existing components).
   For example::
 
      ixgbe: fix offload config option name
@@ -215,54 +226,54 @@ Here are some guidelines for the summary line:
 
 * Use the imperative of the verb (like instructions to the code base).
 
-* Don't add a period/full stop to the subject line or you will end up two in the patch name: ``dpdk_description..patch``.
+* Do not add a period/full stop to the subject line or you will end up with two in the patch name: ``dpdk_description..patch``.
 
 The actual email subject line should be prefixed by ``[PATCH]`` and the version, if greater than v1,
 for example: ``PATCH v2``.
-The is generally added by ``git send-email`` or ``git format-patch``, see below.
+``git send-email`` or ``git format-patch`` generally adds this prefix; see below.
 
-If you are submitting an RFC draft of a feature you can use ``[RFC]`` instead of ``[PATCH]``.
-An RFC patch doesn't have to be complete.
+If you are submitting an RFC draft of a feature, use ``[RFC]`` instead of ``[PATCH]``.
+An RFC patch does not have to be complete.
 It is intended as a way of getting early feedback.
 
 
 Commit Messages: Body
 ---------------------
 
-Here are some guidelines for the body of a commit message:
+Here are guidelines for the body of a commit message:
 
 * The body of the message should describe the issue being fixed or the feature being added.
-  It is important to provide enough information to allow a reviewer to understand the purpose of the patch.
+  Provide enough information to allow a reviewer to understand the purpose of the patch.
 
-* When the change is obvious the body can be blank, apart from the signoff.
+* When the change is obvious, the body can be blank apart from the signoff.
 
-* The commit message must end with a ``Signed-off-by:`` line which is added using::
+* The commit message must end with a ``Signed-off-by:`` line, added using::
 
       git commit --signoff # or -s
 
-  The purpose of the signoff is explained in the
+  The
   `Developer's Certificate of Origin <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1>`_
-  section of the Linux kernel guidelines.
+  section of the Linux kernel guidelines explains the purpose of the signoff.
 
   .. Note::
 
-     All developers must ensure that they have read and understood the
+     All developers must read and understand the
      Developer's Certificate of Origin section of the documentation prior
      to applying the signoff and submitting a patch.
 
 * The signoff must be a real name and not an alias or nickname.
   More than one signoff is allowed.
 
-* The text of the commit message should be wrapped at 72 characters.
+* Wrap the text of the commit message at 72 characters.
 
-* When fixing a regression, it is required to reference the id of the commit
+* When fixing a regression, 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
+  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\")%nCc: %ae'"
 
-  The output of ``git fixline <SHA>`` must then be added to the commit message::
+  Add the output of ``git fixline <SHA>`` to the commit message::
 
      doc: fix some parameter description
 
@@ -274,12 +285,12 @@ Here are some guidelines for the body of a commit message:
      ---
      Cc: author@example.com
 
-* When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
+* When fixing an error or warning, include the error message and instructions on how to reproduce it.
 
-* Use correct capitalization, punctuation and spelling.
+* Use correct capitalization, punctuation, and spelling.
 
-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
+In addition to the ``Signed-off-by:`` name, 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
@@ -287,7 +298,7 @@ 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,
+It is used as a cloud-based service 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::
@@ -308,7 +319,7 @@ in the body of the commit message. For example::
 `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.
+to effectively track 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::
@@ -327,10 +338,10 @@ For example::
 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>`_
+CC all fix patches to the main branch that are candidates for backporting
+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::
+In the commit message body, insert ``Cc: stable@dpdk.org`` as follows::
 
      doc: fix some parameter description
 
@@ -341,19 +352,19 @@ In the commit message body the Cc: stable@dpdk.org should be inserted as follows
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
 
-For further information on stable contribution you can go to
+For further information on stable contribution, see
 :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
+Sometimes a patch or patch set depends on another one.
+To help the maintainers and automation tasks, document this dependency in the 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::
+Where ``NNNNN`` is the patchwork ID for the patch or series::
 
      doc: fix some parameter description
 
@@ -366,7 +377,7 @@ Where ``NNNNN`` is patchwork ID for patch or series::
 Tag order
 ~~~~~~~~~
 
-There is a pattern indicating how certain tags should relate to each other.
+A pattern indicates how certain tags should relate to each other.
 
 Example of proper tag sequence::
 
@@ -382,22 +393,22 @@ Example of proper tag sequence::
      Reviewed-by:
      Tested-by:
 
-Between first and second tag section there is and empty line.
+An empty line separates the first and second tag sections.
 
-While ``Signed-off-by:`` is an obligatory tag and must exist in each commit,
+While ``Signed-off-by:`` is obligatory and must exist in each commit,
 all other tags are optional.
-Any tag, as long as it is in proper location to other adjacent tags (if present),
+Any tag, as long as it is in proper location relative to other adjacent tags (if present),
 may occur multiple times.
 
-Tags after the first occurrence of ``Signed-off-by:`` shall be laid out
-in a chronological order.
+Place tags after the first occurrence of ``Signed-off-by:``
+in chronological order.
 
 
 Creating Patches
 ----------------
 
-It is possible to send patches directly from git but for new contributors it is recommended to generate the
-patches with ``git format-patch`` and then when everything looks okay, and the patches have been checked, to
+You can send patches directly from git, but for new contributors it is recommended to generate the
+patches with ``git format-patch`` and then, when everything looks okay and the patches have been checked,
 send them with ``git send-email``.
 
 Here are some examples of using ``git format-patch`` to generate patches:
@@ -413,15 +424,15 @@ Here are some examples of using ``git format-patch`` to generate patches:
    # Generate the patches in a directory.
    git format-patch -3 -o ~/patch/
 
-   # Add a cover letter to explain a patchset.
+   # Add a cover letter to explain a patch set.
    git format-patch -3 -o ~/patch/ --cover-letter
 
    # Add a prefix with a version number.
    git format-patch -3 -o ~/patch/ -v 2
 
 
-Cover letters are useful for explaining a patchset and help to generate a logical threading to the patches.
-Smaller notes can be put inline in the patch after the ``---`` separator, for example::
+Cover letters are useful for explaining a patch set and help generate logical threading to the patches.
+Put smaller notes inline in the patch after the ``---`` separator, for example::
 
    Subject: [PATCH] fm10k/base: add FM10420 device ids
 
@@ -438,8 +449,8 @@ Smaller notes can be put inline in the patch after the ``---`` separator, for ex
     2 files changed, 12 insertions(+)
    ...
 
-Version 2 and later of a patchset should also include a short log of the changes so the reviewer knows what has changed.
-This can be added to the cover letter or the annotations.
+Version 2 and later of a patch set should also include a short log of the changes so the reviewer knows what has changed.
+Add this to the cover letter or the annotations.
 For example::
 
    ---
@@ -457,32 +468,32 @@ For example::
 Checking the Patches
 --------------------
 
-Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``devtools``
+Check patches for formatting and syntax issues using the ``checkpatches.sh`` script in the ``devtools``
 directory of the DPDK repo.
-This uses the Linux kernel development tool ``checkpatch.pl`` which  can be obtained by cloning, and periodically,
-updating the Linux kernel sources.
+This uses the Linux kernel development tool ``checkpatch.pl``, which can be obtained by cloning, and periodically
+updating, the Linux kernel sources.
 
-The path to the original Linux script must be set in the environment variable ``DPDK_CHECKPATCH_PATH``.
+Set the path to the original Linux script in the environment variable ``DPDK_CHECKPATCH_PATH``.
 
 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
+Specify a different dictionary path
 in the environment variable ``DPDK_CHECKPATCH_CODESPELL``.
 
-There is a DPDK script to build an adjusted dictionary
+A DPDK script builds 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::
+The development tools load environment variables
+from the following files, in order of preference::
 
    .develconfig
    ~/.config/dpdk/devel.config
    /etc/dpdk/devel.config.
 
-Once the environment variable is set, the script can be run as follows::
+Once the environment variable is set, run the script as follows::
 
    devtools/checkpatches.sh ~/patch/
 
@@ -490,34 +501,34 @@ The script usage is::
 
    checkpatches.sh [-h] [-q] [-v] [-nX|-r range|patch1 [patch2] ...]
 
-Then the git logs should be checked using the ``check-git-log.sh`` script.
+Then check the git logs using the ``check-git-log.sh`` script.
 
 The script usage is::
 
    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.
+For both scripts, the -n option specifies a number of commits from HEAD,
+and the -r option specifies a ``git log`` range.
 
-Additionally, when contributing to the DTS tool, patches should also be checked using
+Additionally, when contributing to the DTS tool, check patches using
 the ``dts-check-format.sh`` script in the ``devtools`` directory of the DPDK repo.
-To run the script, extra :ref:`Python dependencies <dts_deps>` are needed.
+Running the script requires extra :ref:`Python dependencies <dts_deps>`.
 
 .. _contrib_check_compilation:
 
 Checking Compilation
 --------------------
 
-Compilation of patches is to be tested with ``devtools/test-meson-builds.sh`` script.
+Test compilation of patches with the ``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
+By default, each build goes in a subfolder of the current working directory.
+However, to place the builds in a different location,
+set the environment variable ``DPDK_BUILD_TEST_DIR`` to that desired location.
+For example, setting ``DPDK_BUILD_TEST_DIR=__builds`` puts 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.
+Setting ``DPDK_BUILD_TEST_DIR`` to an absolute directory path (e.g., ``/tmp``) is also supported.
 
 
 .. _integrated_abi_check:
@@ -527,15 +538,15 @@ Checking ABI compatibility
 
 By default, ABI compatibility checks are disabled.
 
-To enable them, a reference version must be selected via the environment
+To enable them, select a reference version 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 ``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
+The ``devtools/test-meson-builds.sh`` script then builds this reference version
+in a temporary directory and stores 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.
+Set the environment variable ``DPDK_ABI_REF_DIR`` to place the results in
+a different location.
 
 Sample::
 
@@ -545,8 +556,8 @@ Sample::
 Sending Patches
 ---------------
 
-Patches should be sent to the mailing list using ``git send-email``.
-You can configure an external SMTP with something like the following::
+Send patches to the mailing list using ``git send-email``.
+Configure an external SMTP with something like the following::
 
    [sendemail]
        smtpuser = name@domain.com
@@ -556,27 +567,31 @@ You can configure an external SMTP with something like the following::
 
 See the `Git send-email <https://git-scm.com/docs/git-send-email>`_ documentation for more details.
 
-The patches should be sent to ``dev@dpdk.org``.
-If the patches are a change to existing files then you should send them TO the maintainer(s) and CC ``dev@dpdk.org``.
-The appropriate maintainer can be found in the ``MAINTAINERS`` file::
+Send patches to ``dev@dpdk.org``.
+If the patches change existing files, send them TO the maintainer(s) and CC ``dev@dpdk.org``.
+Find the appropriate maintainer 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::
+The script ``get-maintainer.sh`` can select maintainers automatically::
 
   git send-email --to-cmd ./devtools/get-maintainer.sh --cc dev@dpdk.org 000*.patch
 
-You can test the emails by sending it to yourself or with the ``--dry-run`` option.
+Send new additions without a maintainer::
+
+   git send-email --to dev@dpdk.org 000*.patch
+
+Test the emails by sending them to yourself or with the ``--dry-run`` option.
 
-If the patch is in relation to a previous email thread you can add it to the same thread using the Message ID::
+If the patch relates to a previous email thread, add it to the same thread using the Message ID::
 
    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,
+Find the Message ID in the raw text of emails or at the top of each Patchwork patch,
 `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.
+Once submitted, your patches appear on the mailing list and in Patchwork.
 
 Experienced committers may send patches directly with ``git send-email`` without the ``git format-patch`` step.
 The options ``--annotate`` and ``confirm = always`` are recommended for checking patches before sending.
@@ -587,11 +602,11 @@ 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``,
+In this case, send the patch(es) 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
+Given that multiple stable releases are maintained simultaneously,
+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.
 
@@ -599,7 +614,7 @@ and also optionally in the cover letter or in the annotation.
 The Review Process
 ------------------
 
-Patches are reviewed by the community, relying on the experience and
+The community reviews patches, relying on the experience and
 collaboration of the members to double-check each other's work. There are a
 number of ways to indicate that you have checked a patch on the mailing list.
 
@@ -607,8 +622,8 @@ number of ways to indicate that you have checked a patch on the mailing list.
 Tested, Acked and Reviewed by
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To indicate that you have interacted with a patch on the mailing list you
-should respond to the patch in an email with one of the following tags:
+To indicate that you have interacted with a patch on the mailing list,
+respond to the patch in an email with one of the following tags:
 
  * Reviewed-by:
  * Acked-by:
@@ -626,36 +641,35 @@ tag is given here for reference:
 
 .. _statement: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight
 
-``Reviewed-by:`` is a strong statement_ that the patch is an appropriate state
+``Reviewed-by:`` is a strong statement_ that the patch is in an appropriate state
 for merging without any remaining serious technical issues. Reviews from
-community members who are known to understand the subject area and to perform
-thorough reviews will increase the likelihood of the patch getting merged.
+community members who understand the subject area and perform
+thorough reviews increase the likelihood of the patch getting merged.
 
-``Acked-by:`` is a record that the person named was not directly involved in
-the preparation of the patch but wishes to signify and record their acceptance
+``Acked-by:`` records that the person named was not directly involved in
+preparing the patch but wishes to signify and record their acceptance
 and approval of it.
 
-``Tested-by:`` indicates that the patch has been successfully tested (in some
-environment) by the person named.
+``Tested-by:`` indicates that the person named has successfully tested the patch
+(in some environment).
 
-``Reported-by:`` is used to acknowledge person who found or reported the bug.
+``Reported-by:`` acknowledges the person who found or reported the bug.
 
-``Suggested-by:`` indicates that the patch idea was suggested by the named
-person.
+``Suggested-by:`` indicates that the named person suggested the patch idea.
 
 
 Frequency and volume of patches
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Please allow at least 24 hours to pass between posting patch revisions.
+Allow at least 24 hours between posting patch revisions.
 This ensures reviewers from different geographical regions have time to provide feedback.
-Additionally, please do not wait too long (read: weeks) between revisions
+Additionally, do not wait too long (i.e., weeks) between revisions
 as this makes it harder for reviewers and maintainers
 to recall the context of the previous posting.
 If you have not received any feedback within a week,
 it is appropriate to send a ping to the mailing list.
 
-Please do not post new revisions without addressing all feedback.
+Do not post new revisions without addressing all feedback.
 Make sure that all outstanding items have been addressed
 before posting a new revision for review
 (this should involve replying to all the feedback).
@@ -671,18 +685,18 @@ Your changes are expected to pass on an x86/x86-64 Linux system.
 The infrastructure running the tests is a shared resource among all developers on the project,
 and many frequent reposts will result in delays for all developers.
 We do our best to include CI and self-test infrastructure
-that can be used on an individual developer basis.
+that developers can use individually.
 
 For details on running the unit tests, see :doc:`unit_test`.
 It is also recommended to run the :doc:`DTS <../tools/dts>` comprehensive tests.
 Finally, you can also push to a branch on the GitHub service
 to trigger a comprehensive set of compile and unit test runs.
 
-Please keep all patch sets to a reasonable length.
-Too many or too large patches and series can quickly become very difficult
-for a reasonable review.
-It is recommended to appropriately split patches and series
-to groups of digestible logical changes.
+Keep all patch sets to a reasonable length.
+Too many or too large patches and series can quickly become difficult
+to review reasonably.
+Appropriately split patches and series
+into groups of digestible logical changes.
 
 
 Steps to getting your patch merged
@@ -695,39 +709,39 @@ patch accepted. The general cycle for patch review and acceptance is:
 
 #. Check the automatic test reports in the coming hours.
 
-#. Wait for review comments. While you are waiting review some other patches.
+#. Wait for review comments. While you are waiting, review some other patches.
 
-#. Fix the review comments and submit a ``v n+1`` patchset::
+#. Fix the review comments and submit a ``v n+1`` patch set::
 
       git format-patch -3 -v 2
 
 #. Update Patchwork to mark your previous patches as "Superseded".
 
-#. If the patch is deemed suitable for merging by the relevant maintainer(s) or other developers they will ``ack``
+#. If the relevant maintainer(s) or other developers deem the patch suitable for merging, they will ``ack``
    the patch with an email that includes something like::
 
       Acked-by: Alex Smith <alex.smith@example.com>
 
-   **Note**: When acking patches please remove as much of the text of the patch email as possible.
+   **Note**: When acking patches, remove as much of the text of the patch email as possible.
    It is generally best to delete everything after the ``Signed-off-by:`` line.
 
 #. Having the patch ``Reviewed-by:`` and/or ``Tested-by:`` will also help the patch to be accepted.
 
-#. If the patch isn't deemed suitable based on being out of scope or conflicting with existing functionality
+#. If the patch is deemed unsuitable based on being out of scope or conflicting with existing functionality,
    it may receive a ``nack``.
    In this case you will need to make a more convincing technical argument in favor of your patches.
 
-#. In addition a patch will not be accepted if it doesn't address comments from a previous version with fixes or
+#. In addition, a patch will not be accepted if it does not address comments from a previous version with fixes or
    valid arguments.
 
-#. It is the responsibility of a maintainer to ensure that patches are reviewed and to provide an ``ack`` or
+#. Maintainers are responsible for ensuring that patches are reviewed and for providing an ``ack`` or
    ``nack`` of those patches as appropriate.
 
-#. Once a patch has been acked by the relevant maintainer, reviewers may still comment on it for a further
+#. Once the relevant maintainer has acked a patch, reviewers may still comment on it for a further
    two weeks. After that time, the patch should be merged into the relevant git tree for the next release.
    Additional notes and restrictions:
 
-   * Patches should be acked by a maintainer at least two days before the release merge
+   * Maintainers should ack patches at least two days before the release merge
      deadline, in order to make that release.
    * For patches acked with less than two weeks to go to the merge deadline, all additional
      comments should be made no later than two days before the merge deadline.
@@ -742,11 +756,11 @@ patch accepted. The general cycle for patch review and acceptance is:
 Milestones definition
 ---------------------
 
-Each DPDK release has milestones that help everyone to converge to the release date.
+Each DPDK release has milestones that help everyone converge to the release date.
 The following is a list of these milestones together with
 concrete definitions and expectations for a typical release cycle.
-An average cycle lasts 3 months and have 4 release candidates in the last month.
-Test reports are expected to be received after each release candidate.
+An average cycle lasts 3 months and has 4 release candidates in the last month.
+Test reports are expected after each release candidate.
 The number and expectations of release candidates might vary slightly.
 The schedule is updated in the `roadmap <https://core.dpdk.org/roadmap/#dates>`_.
 
@@ -759,14 +773,14 @@ Roadmap
 ~~~~~~~
 
 * Announce new features in libraries, drivers, applications, and examples.
-* To be published before the previous release.
+* Publish before the previous release.
 
 Proposal Deadline
 ~~~~~~~~~~~~~~~~~
 
-* Must send an RFC (Request For Comments) or a complete patch of new features.
+* Send an RFC (Request For Comments) or a complete patch of new features.
 * Early RFC gives time for design review before complete implementation.
-* Should include at least the API changes in libraries and applications.
+* Include at least the API changes in libraries and applications.
 * Library code should be quite complete at the deadline.
 * Nice to have: driver implementation, example code, and documentation.
 
@@ -774,15 +788,15 @@ rc1
 ~~~
 
 * Priority: libraries. No library feature should be accepted after -rc1.
-* API changes or additions must be implemented in libraries.
+* Implement API changes or additions in libraries.
 * The API must include Doxygen documentation
   and be part of the relevant .rst files (library-specific and release notes).
-* API should be used in a test application (``/app``).
+* Use the API in a test application (``/app``).
 * At least one PMD should implement the API.
   It may be a draft sent in a separate series.
-* The above should be sent to the mailing list at least 2 weeks before -rc1
-  to give time for review and maintainers approval.
-* If no review after 10 days, a reminder should be sent.
+* Send the above to the mailing list at least 2 weeks before -rc1
+  to give time for review and maintainer approval.
+* If no review after 10 days, send a reminder.
 * Nice to have: example code (``/examples``)
 
 rc2
@@ -791,17 +805,17 @@ rc2
 * Priority: drivers. No driver feature should be accepted after -rc2.
 * A driver change must include documentation
   in the relevant .rst files (driver-specific and release notes).
-* Driver changes should be sent to the mailing list before -rc1 is released.
+* Send driver changes to the mailing list before -rc1 is released.
 
 rc3
 ~~~
 
 * Priority: applications. No application feature should be accepted after -rc3.
-* New functionality that does not depend on libraries update
+* New functionality that does not depend on library updates
   can be integrated as part of -rc3.
 * The application change must include documentation in the relevant .rst files
   (application-specific and release notes if significant).
-* Libraries and drivers cleanup are allowed.
+* Library and driver cleanup is allowed.
 * Small driver reworks.
 
 rc4
@@ -811,4 +825,4 @@ rc4
 * Critical bug fixes only.
 
 .. note::
-   Bug fixes are integrated as early as possible at any stage.
+   Integrate bug fixes as early as possible at any stage.
-- 
2.51.0

[PATCH 09/11] doc: improve stable releases documentation

[Stephen Hemminger]

Rewrite the stable releases and LTS documentation for clarity
- Converting passive voice to active voice
- Restructuring content with bullet points for scannability
- Simplifying verbose explanations
- Removing redundant phrasing
- Making backport criteria more concise

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/stable.rst | 147 ++++++++++++-----------------
 1 file changed, 60 insertions(+), 87 deletions(-)

diff --git a/doc/guides/contributing/stable.rst b/doc/guides/contributing/stable.rst
index 808e7fa779..6065163e75 100644
--- a/doc/guides/contributing/stable.rst
+++ b/doc/guides/contributing/stable.rst
@@ -6,84 +6,69 @@
 DPDK Stable Releases and Long Term Support
 ==========================================
 
-This section sets out the guidelines for the DPDK Stable Releases and the DPDK
-Long Term Support releases (LTS).
-
+This section outlines the guidelines for DPDK Stable Releases and Long Term Support (LTS) releases.
 
 Introduction
 ------------
 
-The purpose of the DPDK Stable Releases is to maintain releases of DPDK with
-backported fixes over an extended period of time. This provides downstream
-consumers of DPDK with a stable target on which to base applications or
-packages.
-
-The primary characteristics of stable releases is that they attempt to
-fix issues and not introduce any new regressions while keeping backwards
-compatibility with the initial release of the stable version.
+The purpose of DPDK Stable Releases is to maintain DPDK versions with backported
+fixes over an extended period. This allows downstream users to base applications
+or packages on a stable, well-maintained version of DPDK.
 
-The Long Term Support release (LTS) is a designation applied to a Stable
-Release to indicate longer term support.
+The primary goal of stable releases is to fix issues without introducing regressions,
+while preserving backward compatibility with the original version.
 
+LTS (Long Term Support) is a designation given to specific stable releases to indicate
+extended support duration.
 
 Stable Releases
 ---------------
 
-Any release of DPDK can be designated as a Stable Release if a
-maintainer volunteers to maintain it and there is a commitment from major
-contributors to validate it before releases.
-If a version is to be a "Stable Release", it should be designated as such
-within one month of that version being initially released.
+Any DPDK release may become a Stable Release if a maintainer volunteers to support it
+and major contributors commit to validating it before each release.
+This designation should be made within one month of the version's initial release.
 
-A Stable Release is used to backport fixes from an ``N`` release back to an
+Stable Releases are typically used to backport fixes from an ``N`` release to an
 ``N-1`` release, for example, from 16.11 to 16.07.
 
-The duration of a stable is one complete release cycle (4 months). It can be
-longer, up to 1 year, if a maintainer continues to support the stable branch,
-or if users supply backported fixes, however the explicit commitment should be
-for one release cycle.
-
-The release cadence is determined by the maintainer based on the number of
-bugfixes and the criticality of the bugs. Releases should be coordinated with
-the validation engineers to ensure that a tagged release has been tested.
-
-
-LTS Release
------------
+* The standard support duration is one full release cycle (4 months).
+* This may extend up to one year if the maintainer continues support or if users provide backported fixes.
+* The maintainer determines the release cadence based on the volume and criticality of fixes.
+* Coordinate releases with validation engineers to ensure proper testing before tagging.
 
-A stable release can be designated as an LTS release based on community
-agreement and a commitment from a maintainer. The current policy is that each
-year's November (X.11) release will be maintained as an LTS for 3 years,
-however that is dependent on continued community support for validation.
+LTS Releases
+------------
 
-After the X.11 release, an LTS branch will be created for it at
-https://git.dpdk.org/dpdk-stable where bugfixes will be backported to.
+A Stable Release can be promoted to an LTS release through community agreement
+and a maintainer's commitment.
 
-A LTS release may align with the declaration of a new major ABI version,
-please read the :doc:`abi_policy` for more information.
+* The current policy designates each November release (X.11) as an LTS and maintains it for 3 years,
+  contingent on community validation support.
+* After release, an LTS branch is created at https://git.dpdk.org/dpdk-stable
+  where bugfixes are backported.
+* An LTS release may align with the declaration of a new major ABI version.
+  See the :doc:`abi_policy` for more information.
 
-It is anticipated that there will be at least 3 releases per year of the LTS
-or approximately 1 every 4 months. This is done to align with the DPDK main
-branch releases so that fixes have already gone through validation as part of
-the DPDK main branch release validation. However, the cadence can be shorter or
-longer depending on the number and criticality of the backported
-fixes. Releases should be coordinated with the validation engineers to ensure
-that a tagged release has been tested.
+Release Cadence:
 
-For a list of the currently maintained stable/LTS branches please see
-the latest `stable roadmap <https://core.dpdk.org/roadmap/#stable>`_.
+* At least three LTS updates per year (roughly one every four months).
+* Aligned with main DPDK releases to leverage shared validation.
+* Frequency may vary depending on the urgency and volume of fixes.
+* Coordinate validation with test engineers.
 
-At the end of the 3 years, a final X.11.N release will be made and at that
-point the LTS branch will no longer be maintained with no further releases.
+For a list of the currently maintained stable/LTS branches, see
+the `stable roadmap <https://core.dpdk.org/roadmap/#stable>`_.
 
+At the end of the 3-year period, a final X.11.N release is made,
+after which the LTS branch is no longer maintained.
 
-What changes should be backported
+What Changes Should Be Backported
 ---------------------------------
 
-Backporting should be limited to bug fixes. All patches accepted on the main
-branch with a Fixes: tag should be backported to the relevant stable/LTS
-branches, unless the submitter indicates otherwise. If there are exceptions,
-they will be discussed on the mailing lists.
+Limit backports to bug fixes.
+
+All patches accepted on the main branch with a ``Fixes:`` tag should be backported
+to the relevant stable/LTS branches, unless the submitter indicates otherwise.
 
 Fixes suitable for backport should have a ``Cc: stable@dpdk.org`` tag in the
 commit message body as follows::
@@ -97,49 +82,37 @@ commit message body as follows::
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
 
-
 Fixes not suitable for backport should not include the ``Cc: stable@dpdk.org`` tag.
 
-To support the goal of stability and not introducing regressions,
-new code being introduced is limited to bug fixes.
 New features should not be backported to stable releases.
-
-In some limited cases, it may be acceptable to backport a new feature
-to a stable release. Some of the factors which impact the decision by
-stable maintainers are as follows:
-
-* Does the feature break API/ABI?
-* Does the feature break backwards compatibility?
-* Is it for the latest LTS release (to avoid LTS upgrade issues)?
-* Is there a commitment from the proposer or affiliation to validate the feature
-  and check for regressions in related functionality?
-* Is there a track record of the proposer or affiliation validating stable releases?
-* Is it obvious that the feature will not impact existing functionality?
-* How intrusive is the code change?
-* What is the scope of the code change?
-* Does it impact common components or vendor specific?
-* Is there a justifiable use case (a clear user need)?
-* Is there a community consensus about the backport?
-
-Performance improvements are generally not considered to be fixes,
-but may be considered in some cases where:
+In limited cases, a new feature may be acceptable if:
+
+* It does not break API or ABI.
+* It preserves backward compatibility.
+* It targets the latest LTS release (to help with upgrade paths).
+* The proposer commits to testing the feature and monitoring regressions.
+* The proposer or their organization has a track record of validating stable releases.
+* It clearly does not impact existing functionality.
+* The change is minimally invasive and scoped.
+* It affects vendor-specific components rather than common ones.
+* There is a justifiable use case (a clear user need).
+* There is community consensus about the backport.
+
+Performance improvements are generally not considered fixes,
+but may be considered in cases where:
 
 * It is fixing a performance regression that occurred previously.
 * An existing feature in LTS is not usable as intended without it.
 
 APIs marked as ``experimental`` are not considered part of the ABI version
-and can be changed without prior notice. This is necessary for the API to be
-improved and stabilized and become part of the ABI version in the future.
-
-However, in LTS releases ``experimental`` API should not be changed as there
-will not be a future ABI version on the branch and compatibility with previous
-release of an LTS version is of the highest importance.
+and can be changed without prior notice in mainline development.
+However, in LTS releases, ``experimental`` APIs should not be changed,
+as compatibility with previous releases of an LTS version is paramount.
 
 The Stable Mailing List
 -----------------------
 
-The Stable and LTS release are coordinated on the stable@dpdk.org mailing
-list.
+Stable and LTS releases are coordinated on the stable@dpdk.org mailing list.
 
 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>`_
@@ -149,7 +122,7 @@ mailing list.
 Releasing
 ---------
 
-A Stable Release will be released by:
+A Stable Release is made by:
 
 * Tagging the release with YY.MM.n (year, month, number).
 * Uploading a tarball of the release to dpdk.org.
-- 
2.51.0

[PATCH 10/11] doc: improve unit test guide readability

[Stephen Hemminger]

Improve the unit test documentation
- Converting passive voice to active voice
- Using imperative mood for instructions
- Simplifying wordy constructions
- Removing unnecessary include statements from code example
- Fixing minor grammar and punctuation issues

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/unit_test.rst | 113 ++++++++++++--------------
 1 file changed, 52 insertions(+), 61 deletions(-)

diff --git a/doc/guides/contributing/unit_test.rst b/doc/guides/contributing/unit_test.rst
index c0f0d2988f..5b22393e6f 100644
--- a/doc/guides/contributing/unit_test.rst
+++ b/doc/guides/contributing/unit_test.rst
@@ -9,7 +9,7 @@ tests to the in-tree DPDK test suites.
 
 The DPDK test suite model is loosely based on the xUnit model,
 where tests are grouped into test suites, and suites are run by runners.
-For a basic overview, see the basic Wikipedia article on `xUnit
+For a basic overview, see the Wikipedia article on `xUnit
 <https://en.wikipedia.org/wiki/XUnit>`_.
 
 
@@ -18,13 +18,13 @@ Background
 
 The in-tree testing infrastructure for DPDK consists of
 multiple applications and support tools.
-The primary tools are the `dpdk-test` application,
+The primary tools are the `dpdk-test` application
 and the ``meson test`` infrastructure.
-These two are the primary ways through which
-a user will interact with the DPDK testing infrastructure.
+These two are the primary ways
+users interact with the DPDK testing infrastructure.
 
-There exists a bit of confusion with the test suite and test case separation
-with respect to `dpdk-test` and ``meson test``.
+Some confusion exists regarding test suite and test case separation
+between `dpdk-test` and ``meson test``.
 Both have a concept of test suite and test case.
 In both, the concept is similar.
 A test suite is a group of test cases,
@@ -36,14 +36,14 @@ to denote a Meson test suite / case.
 Running a test
 --------------
 
-DPDK tests are run via the main test runner, the `dpdk-test` app.
+DPDK tests run via the main test runner, the `dpdk-test` app.
 The `dpdk-test` app is a command-line interface that facilitates
 running various tests or test suites.
 
 There are three modes of operation.
-The first mode is as an interactive command shell
+The first mode is an interactive command shell
 that allows launching specific test suites.
-This is the default operating mode of `dpdk-test` and can be done by::
+This is the default operating mode of `dpdk-test` and can be invoked by::
 
    $ ./build/app/test/dpdk-test --dpdk-options-here
    EAL: Detected 4 lcore(s)
@@ -58,12 +58,12 @@ This is the default operating mode of `dpdk-test` and can be done by::
    APP: HPET is not enabled, using TSC as default timer
    RTE>>
 
-At the prompt, simply type the name of the test suite you wish to run
+At the prompt, type the name of the test suite you wish to run
 and it will execute.
 
-The second form is useful for a scripting environment,
+The second form is useful for a scripting environment
 and is used by the DPDK Meson build system.
-This mode is invoked by
+Invoke this mode by
 assigning a specific test suite name to the environment variable ``DPDK_TEST``
 before invoking the `dpdk-test` command, such as::
 
@@ -84,7 +84,7 @@ before invoking the `dpdk-test` command, such as::
    RTE>>$
 
 The above shows running a specific test case.
-On success, the return code will be '0',
+On success, the return code will be '0';
 otherwise it will be set to some error value (such as '255', or a negative value).
 
 The third form is an alternative
@@ -110,20 +110,20 @@ The unit test app can accept test suite names via command line arguments::
 The primary benefit here is specifying multiple test names,
 which is not possible with the ``DPDK_TEST`` environment variable.
 
-Additionally, it is possible to specify additional test parameters
+Additionally, specify additional test parameters
 via the ``DPDK_TEST_PARAMS`` argument,
 in case some tests need additional configuration.
-This isn't currently used in the Meson test suites.
+This is not currently used in the Meson test suites.
 
 
 Running test cases via Meson
 ----------------------------
 
-In order to allow developers to quickly execute all the standard internal tests
+To allow developers to quickly execute all the standard internal tests
 without needing to remember or look up each test suite name,
 the build system includes a standard way of executing the Meson test suites.
 After building via ``ninja``, the ``meson test`` command
-with no arguments will execute the Meson test suites.
+with no arguments executes the Meson test suites.
 
 There are a number of pre-configured Meson test suites.
 The first is the **fast** test suite, which is the largest group of test cases.
@@ -133,9 +133,9 @@ These test suites can take longer to run and do performance evaluations.
 The third is the **driver** test suite,
 which is mostly for special hardware related testing (such as `cryptodev`).
 The fourth, and currently the last, suite is the **debug** suite.
-These tests mostly are used to dump system information.
+These tests mostly dump system information.
 
-The Meson test suites can be selected by adding the ``--suite`` option
+Select the Meson test suites by adding the ``--suite`` option
 to the ``meson test`` command.
 Ex: ``meson test --suite fast-tests``::
 
@@ -159,19 +159,19 @@ via the command line by adding the test names as an argument::
    1/1 DPDK:fast-tests / version_autotest OK             0.17s
    ...
 
-Note that these test cases must be known to Meson
+Note that Meson must know these test cases
 for the ``meson test`` command to run them.
-Simply adding a new test to the `dpdk-test` application isn't enough.
+Simply adding a new test to the `dpdk-test` application is not enough.
 See the section `Adding a suite or test case to Meson`_ for more details.
 
 
 Adding tests to dpdk-test application
 -------------------------------------
 
-Unit tests should be added to the system
-whenever we introduce new functionality to DPDK,
-as well as whenever a bug is resolved.
-This helps the DPDK project to catch regressions as they are introduced.
+Add unit tests to the system
+whenever introducing new functionality to DPDK
+or resolving a bug.
+This helps the DPDK project catch regressions as they occur.
 
 The DPDK test application supports two layers of tests:
    #. *test cases* which are individual tests
@@ -185,12 +185,12 @@ There are two important functions for interacting with the test harness:
    ``REGISTER_<MESON_SUITE>_TEST(command_name, function_to_execute)``
       Registers a test command with the name `command_name`
       and which runs the function `function_to_execute` when `command_name` is invoked.
-      The test is automatically added to the Meson test suite `<MESON_SUITE>` by this macro.
-      Examples would be ``REGISTER_DRIVER_TEST``, or ``REGISTER_PERF_TEST``.
+      This macro automatically adds the test to the Meson test suite `<MESON_SUITE>`.
+      Examples: ``REGISTER_DRIVER_TEST``, or ``REGISTER_PERF_TEST``.
       **NOTE:** The ``REGISTER_FAST_TEST`` macro is slightly different,
       in that it takes two additional parameters,
-      specifying whether the test can be run using ``--no-huge``,
-      and whether the test can be run using Address Sanitization (ASAN)
+      specifying whether the test can run using ``--no-huge``,
+      and whether the test can run using Address Sanitization (ASAN).
 
    ``unit_test_suite_runner(struct unit_test_suite *)``
       Returns a runner for a full test suite object,
@@ -203,28 +203,19 @@ that runs at the beginning and end of the test suite execution.
 Each unit test has a similar function for test case setup and tear down.
 
 Each test suite may use a nested list of sub-testsuites,
-which are iterated by the ``unit_test_suite_runner``.
+which the ``unit_test_suite_runner`` iterates.
 This support allows for better granularity when designing test suites.
-The sub-testsuites list can also be used in parallel with the vector of test cases,
-in this case the test cases will be run,
-and then each sub-testsuite is executed.
+The sub-testsuites list can also be used in parallel with the vector of test cases;
+in this case, the test cases run first,
+then each sub-testsuite executes.
 To see an example of a test suite using sub-testsuites,
 see *app/test/test_cryptodev.c*.
 
-Test cases are added to the ``.unit_test_cases`` element
-of the appropriate unit test suite structure.
-An example of both a test suite and a case:
+Example of a test suite with a single test case:
 
 .. code-block:: c
    :linenos:
 
-   #include <time.h>
-
-   #include <rte_common.h>
-   #include <rte_cycles.h>
-   #include <rte_hexdump.h>
-   #include <rte_random.h>
-
    #include "test.h"
 
    static int testsuite_setup(void) { return TEST_SUCCESS; }
@@ -256,7 +247,7 @@ An example of both a test suite and a case:
 The above code block is a small example
 that can be used to create a complete test suite with test case.
 
-Sub-testsuites can be added to the ``.unit_test_suites`` element
+Add sub-testsuites to the ``.unit_test_suites`` element
 of the unit test suite structure, for example:
 
 .. code-block:: c
@@ -335,13 +326,13 @@ The first way to indicate a generic error is
 by returning a test result failure, using the ``TEST_FAILED`` error code.
 This is the most basic way of indicating that an error
 has occurred in a test routine.
-It isn't very informative to the user, so it should really be used in cases
+It is not very informative to the user, so use it in cases
 where the test has catastrophically failed.
 
 The preferred method of indicating an error is
 via the ``RTE_TEST_ASSERT`` family of macros,
-which will immediately return ``TEST_FAILED`` error condition,
-but will also log details about the failure.
+which immediately return ``TEST_FAILED`` error condition,
+but also log details about the failure.
 The basic form is:
 
 .. code-block:: c
@@ -350,16 +341,16 @@ The basic form is:
 
 In the above macro, *cond* is the condition to evaluate to **true**.
 Any generic condition can go here.
-The *msg* parameter will be a message to display if *cond* evaluates to **false**.
+The *msg* parameter is a message to display if *cond* evaluates to **false**.
 Some specialized macros already exist.
 See `lib/librte_eal/include/rte_test.h` for a list of defined test assertions.
 
 Sometimes it is important to indicate that a test needs to be skipped,
-either because the environment isn't able to support running the test,
-or because some requisite functionality isn't available.
+either because the environment cannot support running the test,
+or because some requisite functionality is unavailable.
 The test suite supports returning a result of ``TEST_SKIPPED``
 during test case setup, or during test case execution
-to indicate that the preconditions of the test aren't available.
+to indicate that the preconditions of the test are not available.
 Example::
 
    $ meson test -C build --suite fast-tests
@@ -386,10 +377,10 @@ Example::
    $ meson test -C build --suite fast-tests
    $ ninja coverage-html -C build
 
-The above will generate an HTML report
+The above generates an HTML report
 in the `build/meson-logs/coveragereport/` directory
 that can be explored for detailed code covered information.
-This can be used to assist in test development.
+Use this to assist in test development.
 
 
 Adding a suite or test case to Meson
@@ -400,10 +391,10 @@ to register the test in dpdk-test, as described above.
 For example,
 defining the test command using ``REGISTER_PERF_TEST`` automatically
 adds the test to the perf-test meson suite.
-Once added, the new test will be run
+Once added, the new test runs
 as part of the appropriate class (fast, perf, driver, etc.).
 
-A user or developer can confirm that a test is known to Meson
+Confirm that a test is known to Meson
 by using the ``--list`` option::
 
    $ meson test -C build --list
@@ -411,12 +402,12 @@ by using the ``--list`` option::
    DPDK:fast-tests / bitops_autotest
    ...
 
-Some of these test suites are run during continuous integration tests,
+Some of these test suites run during continuous integration tests,
 making regression checking automatic for new patches submitted to the project.
 
 .. note::
 
-   The use of the old ``REGISTER_TEST_COMMAND`` macro
+   The old ``REGISTER_TEST_COMMAND`` macro
    to add a command without adding it to a meson test suite is deprecated.
    All new tests must be added to a test suite
    using the appropriate ``REGISTER_<SUITE>_TEST`` macro.
@@ -424,8 +415,8 @@ making regression checking automatic for new patches submitted to the project.
 Running cryptodev tests
 -----------------------
 
-When running cryptodev tests, the user must create any required virtual device
-via EAL arguments, as this is not automatically done by the test::
+When running cryptodev tests, create any required virtual device
+via EAL arguments, as this is not done automatically by the test::
 
    $ ./build/app/test/dpdk-test --vdev crypto_aesni_mb
    $ meson test -C build --suite driver-tests \
@@ -433,6 +424,6 @@ via EAL arguments, as this is not automatically done by the test::
 
 .. note::
 
-   The ``cryptodev_scheduler_autotest`` is the only exception to this.
-   This vdev will be created automatically by the test app,
+   The ``cryptodev_scheduler_autotest`` is the only exception.
+   This vdev is created automatically by the test app,
    as it requires a more complex setup than other vdevs.
-- 
2.51.0

[PATCH 11/11] doc: improve vulnerability process documentation

[Stephen Hemminger]

Improve the vulnerability management documentation
- Converting passive voice to active voice
- Using clearer section headings
- Simplifying verbose explanations
- Making reporting instructions more direct
- Fixing broken RST link syntax for mailing lists

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/vulnerability.rst | 140 ++++++++++------------
 1 file changed, 65 insertions(+), 75 deletions(-)

diff --git a/doc/guides/contributing/vulnerability.rst b/doc/guides/contributing/vulnerability.rst
index fc60e02e37..1d616d203a 100644
--- a/doc/guides/contributing/vulnerability.rst
+++ b/doc/guides/contributing/vulnerability.rst
@@ -7,10 +7,9 @@ DPDK Vulnerability Management Process
 Scope
 -----
 
-Only the main repositories (dpdk and dpdk-stable) of the core project
-are in the scope of this security process (including experimental APIs).
-If a stable branch is declared unmaintained (end of life),
-no fix will be applied.
+This security process covers only the main repositories (dpdk and dpdk-stable)
+of the core project (including experimental APIs).
+The team will not apply fixes to stable branches declared unmaintained (end of life).
 
 All vulnerabilities are bugs, but not every bug is a vulnerability.
 Vulnerabilities compromise one or more of:
@@ -19,79 +18,71 @@ Vulnerabilities compromise one or more of:
 * Integrity (trustworthiness and correctness).
 * Availability (uptime and service).
 
-If in doubt, please consider the vulnerability as security sensitive.
+If in doubt, consider the vulnerability as security sensitive.
 At worst, the response will be to report the bug through the usual channels.
 
 
-Finding
--------
+Finding Security Issues
+-----------------------
 
 There is no pro-active security engineering effort at the moment.
 
-Please report any security issue you find in DPDK as described below.
+Report any security issue you find in DPDK as described below.
 
 
-Report
-------
+Reporting Security Issues
+-------------------------
 
-Do not use Bugzilla (unsecured).
-Instead, send GPG-encrypted emails
-to `security@dpdk.org <https://core.dpdk.org/security#contact>`_.
-Anyone can post to this list.
-In order to reduce the disclosure of a vulnerability in the early stages,
-membership of this list is intentionally limited to a `small number of people
-<https://mails.dpdk.org/roster/security>`_.
+Do not use Bugzilla to report security vulnerabilities, as it is not secured for such communication.
+Instead, send a GPG-encrypted email to `security@dpdk.org <https://core.dpdk.org/security#contact>`_.
+This address is open to all, but access to its inbox is intentionally limited to a small group
+to minimize the risk of early disclosure.
 
-It is additionally encouraged to GPG-sign one-on-one conversations
-as part of the security process.
+GPG-sign any one-on-one correspondence related to the vulnerability
+report as part of maintaining a secure communication process.
 
-As it is with any bug, the more information provided,
-the easier it will be to diagnose and fix.
-If you already have a fix, please include it with your report,
-as that can speed up the process considerably.
+As with any bug report, detailed information greatly aids in diagnosing and resolving the issue.
+If you have already developed a fix, include it in your submission to help accelerate resolution.
 
-In the report, please note how you would like to be credited
-for discovering the issue
-and the details of any embargo you would like to impose.
+In your report, specify how you would like to be credited for the discovery and mention any embargo
+period you wish to impose.
 
-If the vulnerability is not public yet,
-no patch or information should be disclosed publicly.
-If a fix is already published,
-the reporting process must be followed anyway, as described below.
+If the vulnerability has not yet been made public, do not disclose patches or related information
+publicly. Even if a fix has already been published, you must still follow the proper reporting process outlined here.
 
 
 Confirmation
 ------------
 
-Upon reception of the report, a security team member should reply
-to the reporter acknowledging that the report has been received.
+Upon receiving the report, a security team member should reply
+to the reporter acknowledging receipt.
 
 The DPDK security team reviews the security vulnerability reported.
-Area experts not members of the security team may be involved in the process.
-In case the reported issue is not qualified as a security vulnerability,
+Area experts who are not members of the security team may be involved in the process.
+If the reported issue does not qualify as a security vulnerability,
 the security team will request the submitter to report it
 using the usual channel (Bugzilla).
-If qualified, the security team will assess which DPDK version are affected.
-A bugzilla ID (allocated in a `reserved pool
+If qualified, the security team assesses which DPDK versions are affected.
+A bugzilla ID (allocated from a `reserved pool
 <https://bugs.dpdk.org/buglist.cgi?f1=bug_group&o1=equals&v1=security>`_)
 is assigned to the vulnerability, and kept empty until public disclosure.
 
-The security team calculates the severity score with
+The security team calculates the severity score with the
 `CVSS calculator <https://www.first.org/cvss/calculator/3.0>`_
 based on inputs from the reporter and its own assessment of the vulnerability,
 and agrees on the score with the reporter.
 
 An embargo may be put in place depending on the severity of the vulnerability.
-If an embargo is decided, its duration should be suggested by the security team
-and negotiated with the reporter.
+If an embargo is decided, the security team should suggest the duration
+and negotiate with the reporter.
 Embargo duration between vulnerability confirmation and public disclosure
 should be between **one and ten weeks**.
 If an embargo is not required, the vulnerability may be fixed
 using the standard patch process, once a CVE number has been assigned.
 
-The confirmation mail should be sent within **3 business days**.
+Send the confirmation mail within **3 business days**.
 
-Following information must be included in the mail:
+Include the following information in the mail:
 
 * Confirmation
 * CVSS severity and score
@@ -110,7 +101,7 @@ from the reporter before finalizing the document.
 When the document is final, the security team needs to
 request a CVE identifier from a CNA.
 
-The CVE request should be sent
+Send the CVE request
 to `secalert@redhat.com <mailto:secalert@redhat.com>`_
 using GPG encrypted email
 (see `contact details <https://access.redhat.com/security/team/contact>`_).
@@ -161,19 +152,18 @@ CVE Request Template without Embargo
 Fix Development and Review
 --------------------------
 
-If the fix is already published, this step is skipped,
-and the pre-release disclosure is replaced with the private disclosure,
-as described below. It must not be considered as the standard process.
+If the fix is already published, skip this step,
+and replace the pre-release disclosure with the private disclosure,
+as described below. This should not be considered the standard process.
 
-This step may be started in parallel with CVE creation.
-The patches fixing the vulnerability are developed and reviewed
-by the security team and
-by elected area experts that agree to maintain confidentiality.
+This step may start in parallel with CVE creation.
+The security team and elected area experts who agree to maintain confidentiality
+develop and review patches fixing the vulnerability.
 
-The CVE id and the bug id must be referenced in the patch if there is no
-embargo, or if there is an embargo, but it will be lifted when the release
-including the patch is published. If the embargo is going to be lifted after the
-release, then the CVE and bug ids must be omitted from the commit message.
+Reference the CVE id and the bug id in the patch if there is no
+embargo, or if the embargo will be lifted when the release
+including the patch is published. If the embargo will be lifted after the
+release, omit the CVE and bug ids from the commit message.
 
 Backports to the identified affected versions are done once the fix is ready.
 
@@ -181,32 +171,32 @@ Backports to the identified affected versions are done once the fix is ready.
 Pre-Release Disclosure
 ----------------------
 
-When the fix is ready, the security advisory and patches are sent
+When the fix is ready, send the security advisory and patches
 to downstream stakeholders
 (`security-prerelease@dpdk.org <mailto:security-prerelease@dpdk.org>`_),
 specifying the date and time of the end of the embargo.
-The communicated public disclosure date should be **less than one week**
+The communicated public disclosure date should be **less than one week**.
 
 Downstream stakeholders are expected not to deploy or disclose patches
-until the embargo is passed, otherwise they will be removed from the list.
+until the embargo passes; otherwise they will be removed from the list.
 
 Downstream stakeholders (in `security-prerelease list
-<https://mails.dpdk.org/roster/security-prerelease>`_), are:
+<https://mails.dpdk.org/roster/security-prerelease>`_) are:
 
 * Operating system vendors known to package DPDK
 * Major DPDK users, considered trustworthy by the technical board, who
   have made the request to `techboard@dpdk.org <mailto:techboard@dpdk.org>`_
 
-The `OSS security private mailing list mailto:distros@vs.openwall.org>` will
+The `OSS security private mailing list <mailto:distros@vs.openwall.org>`_ will
 also be contacted one week before the end of the embargo, as indicated by `the
-OSS-security process <https://oss-security.openwall.org/wiki/mailing-lists/distros>`
+OSS-security process <https://oss-security.openwall.org/wiki/mailing-lists/distros>`_
 and using the PGP key listed on the same page, describing the details of the
 vulnerability and sharing the patch[es]. Distributions and major vendors follow
 this private mailing list, and it functions as a single point of contact for
 embargoed advance notices for open source projects.
 
-The security advisory will be based on below template,
-and will be sent signed with a security team's member GPG key.
+The security advisory will be based on the template below,
+and will be sent signed with a security team member's GPG key.
 
 
 Pre-Release Mail Template
@@ -234,7 +224,7 @@ Pre-Release Mail Template
   Please do not make the issue public (or release public patches)
   before this coordinated embargo date.
 
-If the issue is leaked during the embargo, the same procedure is followed
+If the issue is leaked during the embargo, follow the same procedure
 with only a few days delay between the pre-release and the public disclosure.
 
 
@@ -242,9 +232,9 @@ Private Disclosure
 ------------------
 
 If a vulnerability is unintentionally already fixed in the public repository,
-a security advisory is sent to downstream stakeholders
+send a security advisory to downstream stakeholders
 (`security-prerelease@dpdk.org <mailto:security-prerelease@dpdk.org>`_),
-giving few days to prepare for updating before the public disclosure.
+giving a few days to prepare for updating before the public disclosure.
 
 
 Private Disclosure Mail Template
@@ -275,23 +265,23 @@ Private Disclosure Mail Template
 Public Disclosure
 -----------------
 
-On embargo expiration, following tasks will be done simultaneously:
+When the embargo expires, carry out the following actions simultaneously:
 
-* The assigned bug is filled by a member of the security team,
-  with all relevant information, and it is made public.
-* The patches are pushed to the appropriate branches.
-* For long and short term stable branches fixed,
-  new versions should be released.
+* A security team member files the assigned bug with all relevant details and makes it publicly accessible.
 
-Releases on Monday to Wednesday are preferred, so that system administrators
-do not have to deal with security updates over the weekend.
+* Push the associated patches to the appropriate branches.
 
-The security advisory is posted
+* Release updated versions for all affected stable branches, both short-term and long-term.
+
+To ease adoption by system administrators, preferably schedule security releases
+between Monday and Wednesday, avoiding weekends.
+
+Post the security advisory
 to `announce@dpdk.org <mailto:announce@dpdk.org>`_ and to `the public OSS-security
-mailing list <mailto:oss-security@lists.openwall.com>` as soon as the patches
+mailing list <mailto:oss-security@lists.openwall.com>`_ as soon as the patches
 are pushed to the appropriate branches.
 
-Patches are then sent to `dev@dpdk.org <mailto:dev@dpdk.org>`_
+Send patches to `dev@dpdk.org <mailto:dev@dpdk.org>`_
 and `stable@dpdk.org <mailto:stable@dpdk.org>`_ accordingly.
 
 
-- 
2.51.0

[PATCH v2 00/12] doc: improve contributing documentation clarity and style

[Stephen Hemminger]

This patch series improves the readability and consistency of the DPDK
contributing documentation. The changes focus on editorial improvements
without altering any technical content or policies.

Initial work on this was done by Nandini Persad. This follow-up series
uses AI assistance for broader coverage across all contributing guides.

The primary improvements across this series include:

- Converting passive voice to active voice for clearer, more direct prose
- Using imperative mood for guidelines and instructions
- Removing redundant phrases ("Please note that", "It is recommended that")
- Simplifying wordy constructions
- Fixing grammar, punctuation, and typos
- Improving consistency in terminology

Summary of changes by document:

  design.rst          - Fix "executive environment" typo, improve clarity
  abi_policy.rst      - Active voice, simplify ABI change descriptions
  coding_style.rst    - Imperative mood for style guidance
  documentation.rst   - Active voice for Doxygen documentation instructions
  linux_uapi.rst      - Simplify uAPI header import instructions
  new_driver.rst      - Direct language for driver contribution process
  new_library.rst     - Simplify library approval process description
  patches.rst         - Comprehensive style improvements throughout
  stable.rst          - Restructure for scannability, concise backport criteria
  vulnerability.rst   - Active voice for security process steps
  unit_test.rst       - Fix grammar issues, consistent command formatting
  abi_versioning.rst  - Fix typos and grammar errors

These changes make the documentation more accessible to new contributors
and align with modern technical writing best practices.

v2:
- Rebased on latest main
- Incorporated additional grammar fixes in unit_test.rst and abi_versioning.rst
- Fixed inconsistent backtick usage for command references

Nandini Persad (1):
  doc: correct grammar and typos in design guide

Stephen Hemminger (11):
  doc: improve ABI policy documentation style
  doc: improve coding style guide readability
  doc: improve documentation guidelines style
  doc: improve Linux uAPI header documentation
  doc: improve new driver guide readability
  doc: improve new library guide style
  doc: improve patch submission guide readability
  doc: improve stable releases documentation
  doc: improve vulnerability process documentation
  doc: improve unit test guide readability
  doc: fix grammar and style in ABI versioning guide

 doc/guides/contributing/abi_policy.rst      | 194 +++++++-------
 doc/guides/contributing/abi_versioning.rst  |  32 +--
 doc/guides/contributing/coding_style.rst    |  20 +-
 doc/guides/contributing/design.rst          |  71 +++---
 doc/guides/contributing/documentation.rst   |   6 +-
 doc/guides/contributing/linux_uapi.rst      |  40 +--
 doc/guides/contributing/new_driver.rst      |  62 ++---
 doc/guides/contributing/new_library.rst     |  20 +-
 doc/guides/contributing/patches.rst         | 434 ++++++++++++++--------------
 doc/guides/contributing/stable.rst          | 147 +++++-----
 doc/guides/contributing/unit_test.rst       | 129 ++++-----
 doc/guides/contributing/vulnerability.rst   | 140 ++++-----
 12 files changed, 637 insertions(+), 658 deletions(-)

-- 
2.51.0

[PATCH v2 01/12] doc: correct grammar and typos in design guide

[Stephen Hemminger]

Changes:
- Use "execution environment" consistently (not "executive environment")
- Fix FreeBSD capitalization
- Use plural "these execution environments" to match multiple options
- Add hyphen to "non-exhaustive"
- Add missing comma before *telemetry*
- Remove double space
- Minor rewording for clarity

Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/design.rst | 71 ++++++++++++++++--------------
 1 file changed, 39 insertions(+), 32 deletions(-)

diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst
index 5517613424..a966da2ddd 100644
--- a/doc/guides/contributing/design.rst
+++ b/doc/guides/contributing/design.rst
@@ -1,6 +1,7 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright 2018 The DPDK contributors
 
+
 Design
 ======
 
@@ -8,22 +9,26 @@ Design
 Environment or Architecture-specific Sources
 --------------------------------------------
 
-In DPDK and DPDK applications, some code is specific to an architecture (i686, x86_64) or to an executive environment (freebsd or linux) and so on.
-As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL.
+In DPDK and DPDK applications, some code is architecture-specific (i686, x86_64) or environment-specific (FreeBSD or Linux, etc.).
+When feasible, such instances of architecture or env-specific code should be provided via standard APIs in the EAL.
+
+By convention, a file is specific if the directory is indicated. Otherwise, it is common.
+
+For example:
 
-By convention, a file is common if it is not located in a directory indicating that it is specific.
-For instance, a file located in a subdir of "x86_64" directory is specific to this architecture.
+A file located in a subdir of "x86_64" directory is specific to this architecture.
 A file located in a subdir of "linux" is specific to this execution environment.
 
 .. note::
 
    Code in DPDK libraries and applications should be generic.
-   The correct location for architecture or executive environment specific code is in the EAL.
+   The correct location for architecture or execution environment-specific code is in the EAL.
 
-When absolutely necessary, there are several ways to handle specific code:
+When necessary, there are several ways to handle specific code:
+
+
+* When the differences are small and they can be embedded in the same C file, use a ``#ifdef`` with a build definition macro in the C code.
 
-* Use a ``#ifdef`` with a build definition macro in the C code.
-  This can be done when the differences are small and they can be embedded in the same C file:
 
   .. code-block:: c
 
@@ -33,9 +38,9 @@ When absolutely necessary, there are several ways to handle specific code:
      titi();
      #endif
 
-* Use build definition macros and conditions in the Meson build file. This is done when the differences are more significant.
-  In this case, the code is split into two separate files that are architecture or environment specific.
-  This should only apply inside the EAL library.
+
+* When the differences are more significant, use build definition macros and conditions in the Meson build file. In this case, the code is split into two separate files that are architecture or environment specific. This should only apply inside the EAL library.
+
 
 Per Architecture Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -43,15 +48,16 @@ Per Architecture Sources
 The following macro options can be used:
 
 * ``RTE_ARCH`` is a string that contains the name of the architecture.
-* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_X32``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_RISCV``, ``RTE_ARCH_LOONGARCH``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` are defined only if we are building for those architectures.
+* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_X32``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_RISCV``, ``RTE_ARCH_LOONGARCH``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` are defined when building for these architectures.
+
 
 Per Execution Environment Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following macro options can be used:
 
-* ``RTE_EXEC_ENV_NAME`` is a string that contains the name of the executive environment.
-* ``RTE_EXEC_ENV_FREEBSD``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` are defined only if we are building for this execution environment.
+* ``RTE_EXEC_ENV_NAME`` is a string that contains the name of the execution environment.
+* ``RTE_EXEC_ENV_FREEBSD``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` are defined only if we are building for these execution environments.
 
 Mbuf features
 -------------
@@ -66,7 +72,7 @@ The "dynamic" area is eating the remaining space in mbuf,
 and some existing "static" fields may need to become "dynamic".
 
 Adding a new static field or flag must be an exception matching many criteria
-like (non exhaustive): wide usage, performance, size.
+like (non-exhaustive): wide usage, performance, size.
 
 
 Runtime Information - Logging, Tracing and Telemetry
@@ -82,11 +88,11 @@ DPDK provides a number of built-in mechanisms to provide this introspection:
 
 Each of these has its own strengths and suitabilities for use within DPDK components.
 
-Below are some guidelines for when each should be used:
+Here are guidelines for when each mechanism should be used:
 
 * For reporting error conditions, or other abnormal runtime issues, *logging* should be used.
-  Depending on the severity of the issue, the appropriate log level, for example,
-  ``ERROR``, ``WARNING`` or ``NOTICE``, should be used.
+  For example, depending on the severity of the issue, the appropriate log level,
+  ``ERROR``, ``WARNING`` or ``NOTICE`` should be used.
 
 .. note::
 
@@ -96,24 +102,24 @@ Below are some guidelines for when each should be used:
 
 * For component initialization, or other cases where a path through the code
   is only likely to be taken once,
-  either *logging* at ``DEBUG`` level or *tracing* may be used, or potentially both.
+  either *logging* at ``DEBUG`` level or *tracing* may be used, or both.
   In the latter case, tracing can provide basic information as to the code path taken,
   with debug-level logging providing additional details on internal state,
-  not possible to emit via tracing.
+  which is not possible to emit via tracing.
 
 * For a component's data-path, where a path is to be taken multiple times within a short timeframe,
   *tracing* should be used.
   Since DPDK tracing uses `Common Trace Format <https://diamon.org/ctf/>`_ for its tracing logs,
   post-analysis can be done using a range of external tools.
 
-* For numerical or statistical data generated by a component, for example, per-packet statistics,
+* For numerical or statistical data generated by a component, such as per-packet statistics,
   *telemetry* should be used.
 
-* For any data where the data may need to be gathered at any point in the execution
-  to help assess the state of the application component,
-  for example, core configuration, device information, *telemetry* should be used.
+* For any data that may need to be gathered at any point during the execution
+  to help assess the state of the application component (for example, core configuration, device information), *telemetry* should be used.
   Telemetry callbacks should not modify any program state, but be "read-only".
 
+
 Many libraries also include a ``rte_<libname>_dump()`` function as part of their API,
 writing verbose internal details to a given file-handle.
 New libraries are encouraged to provide such functions where it makes sense to do so,
@@ -135,13 +141,12 @@ requirements for preventing ABI changes when implementing statistics.
 Mechanism to allow the application to turn library statistics on and off
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Having runtime support for enabling/disabling library statistics is recommended,
-as build-time options should be avoided. However, if build-time options are used,
-for example as in the table library, the options can be set using c_args.
-When this flag is set, all the counters supported by current library are
+Having runtime support for enabling/disabling library statistics is recommended
+as build-time options should be avoided. However, if build-time options are used, as in the table library, the options can be set using c_args.
+When this flag is set, all the counters supported by the current library are
 collected for all the instances of every object type provided by the library.
 When this flag is cleared, none of the counters supported by the current library
-are collected for any instance of any object type provided by the library:
+are collected for any instance of any object type provided by the library.
 
 
 Prevention of ABI changes due to library statistics support
@@ -165,8 +170,8 @@ Motivation to allow the application to turn library statistics on and off
 
 It is highly recommended that each library provides statistics counters to allow
 an application to monitor the library-level run-time events. Typical counters
-are: number of packets received/dropped/transmitted, number of buffers
-allocated/freed, number of occurrences for specific events, etc.
+are: the number of packets received/dropped/transmitted, the number of buffers
+allocated/freed, the number of occurrences for specific events, etc.
 
 However, the resources consumed for library-level statistics counter collection
 have to be spent out of the application budget and the counters collected by
@@ -198,6 +203,7 @@ applications:
   the application may decide to turn the collection of statistics counters off for
   Library X and on for Library Y.
 
+
 The statistics collection consumes a certain amount of CPU resources (cycles,
 cache bandwidth, memory bandwidth, etc) that depends on:
 
@@ -218,6 +224,7 @@ cache bandwidth, memory bandwidth, etc) that depends on:
   validated for header integrity, counting the number of bits set in a bitmask
   might be needed.
 
+
 PF and VF Considerations
 ------------------------
 
@@ -229,5 +236,5 @@ Developers should work with the Linux Kernel community to get the required
 functionality upstream. PF functionality should only be added to DPDK for
 testing and prototyping purposes while the kernel work is ongoing. It should
 also be marked with an "EXPERIMENTAL" tag. If the functionality isn't
-upstreamable then a case can be made to maintain the PF functionality in DPDK
+upstreamable, then a case can be made to maintain the PF functionality in DPDK
 without the EXPERIMENTAL tag.
-- 
2.51.0

Re: [PATCH v2 01/12] doc: correct grammar and typos in design guide

[Stephen Hemminger]

On Fri, 16 Jan 2026 12:14:19 -0800
Stephen Hemminger <stephen@networkplumber.org> wrote:

> Changes:
> - Use "execution environment" consistently (not "executive environment")
> - Fix FreeBSD capitalization
> - Use plural "these execution environments" to match multiple options
> - Add hyphen to "non-exhaustive"
> - Add missing comma before *telemetry*
> - Remove double space
> - Minor rewording for clarity
> 
> Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
> Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> ---

Integrated into https://patchwork.dpdk.org/project/dpdk/patch/20260118191323.241013-8-stephen@networkplumber.org/

[PATCH v2 02/12] doc: improve ABI policy documentation style

[Stephen Hemminger]

Improve readability of the ABI policy documentation
- Converting passive voice to active voice
- Removing redundant phrases like "Please note that" and "Note that"
- Simplifying wordy constructions
- Using imperative mood for guidelines
- Fixing punctuation and grammar issues

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/abi_policy.rst | 194 ++++++++++++-------------
 1 file changed, 96 insertions(+), 98 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index f03a7467ac..2d1c17963d 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -7,7 +7,7 @@ ABI Policy
 Description
 -----------
 
-This document details the management policy that ensures the long-term stability
+This document details the management policy for ensuring long-term stability
 of the DPDK ABI and API.
 
 General Guidelines
@@ -16,28 +16,27 @@ General Guidelines
 #. Major ABI versions are declared no more frequently than yearly. Compatibility
    with the major ABI version is mandatory in subsequent releases until a
    :ref:`new major ABI version <new_abi_version>` is declared.
-#. Major ABI versions are usually but not always declared aligned with a
+#. Major ABI versions usually, but not always, align with a
    :ref:`LTS release <stable_lts_releases>`.
-#. The ABI version is managed at a project level in DPDK, and is reflected in
-   all non-experimental :ref:`library's soname <what_is_soname>`.
-#. The ABI should be preserved and not changed lightly. ABI changes must follow
+#. DPDK manages the ABI version at a project level, reflecting it
+   in all non-experimental :ref:`library sonames <what_is_soname>`.
+#. Preserve the ABI and avoid changing it lightly. ABI changes must follow
    the outlined :ref:`deprecation process <abi_changes>`.
-#. The addition of symbols is generally not problematic. The modification of
-   symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
-#. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
-   once approved these will form part of the next ABI version.
+#. Adding symbols is generally not problematic. Manage modification of
+   symbols with :ref:`ABI Versioning <abi_versioning>`.
+#. Removing symbols is considered an :ref:`ABI breakage <abi_breakages>`;
+   once approved, these removals form part of the next ABI version.
 #. Libraries or APIs marked as :ref:`experimental <experimental_apis>`
    may be changed or removed without prior notice,
    as they are not considered part of an ABI version.
    The :ref:`experimental <experimental_apis>` status of an API
    is not an indefinite state.
-#. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
-   support for hardware which was previously supported, should be treated as an
-   ABI change.
+#. Treat updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
+   support for previously supported hardware, as an ABI change.
 
 .. note::
 
-   Please note that this policy does not currently apply to the
+   This policy does not currently apply to the
    :doc:`Windows build <../windows_gsg/intro>`.
 
 What is an ABI?
@@ -45,13 +44,12 @@ What is an ABI?
 
 An ABI (Application Binary Interface) is the set of runtime interfaces exposed
 by a library. It is similar to an API (Application Programming Interface) but
-is the result of compilation.  It is also effectively cloned when applications
-link to dynamic libraries.  That is to say when an application is compiled to
-link against dynamic libraries, it is assumed that the ABI remains constant
-between the time the application is compiled/linked, and the time that it runs.
-Therefore, in the case of dynamic linking, it is critical that an ABI is
-preserved, or (when modified), done in such a way that the application is unable
-to behave improperly or in an unexpected fashion.
+is the result of compilation. Applications effectively clone the ABI when
+linking to dynamic libraries. When an application compiles and links against
+dynamic libraries, the ABI must remain constant between compile/link time
+and runtime. Therefore, in the case of dynamic linking, it is critical to
+preserve the ABI, or (when modifying it) to do so in a way that prevents
+the application from behaving improperly or unexpectedly.
 
 .. _figure_what_is_an_abi:
 
@@ -64,12 +62,12 @@ What is an ABI version?
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 An ABI version is an instance of a library's ABI at a specific release. Certain
-releases are considered to be milestone releases, the yearly LTS release for
+releases are considered milestone releases, the yearly LTS release for
 example. The ABI of a milestone release may be declared as a 'major ABI
 version', where this ABI version is then supported for some number of subsequent
 releases and is annotated in the library's :ref:`soname<what_is_soname>`.
 
-ABI version support in subsequent releases facilitates application upgrades, by
+ABI version support in subsequent releases facilitates application upgrades by
 enabling applications built against the milestone release to upgrade to
 subsequent releases of a library without a rebuild.
 
@@ -80,14 +78,14 @@ The DPDK ABI policy
 -------------------
 
 A new major ABI version is declared no more frequently than yearly, with
-declarations usually aligning with a LTS release, e.g. ABI 21 for DPDK 20.11.
+declarations usually aligning with an LTS release, e.g., ABI 21 for DPDK 20.11.
 Compatibility with the major ABI version is then mandatory in subsequent
-releases until the next major ABI version is declared, e.g. ABI 22 for DPDK
+releases until the next major ABI version is declared, e.g., ABI 22 for DPDK
 21.11.
 
 At the declaration of a major ABI version, major version numbers encoded in
 libraries' sonames are bumped to indicate the new version, with the minor
-version reset to ``0``. An example would be ``librte_eal.so.21.3`` would become
+version reset to ``0``. For example, ``librte_eal.so.21.3`` becomes
 ``librte_eal.so.22.0``.
 
 The ABI may then change multiple times, without warning, between the last major
@@ -96,12 +94,12 @@ that ABI compatibility with the major ABI version is preserved and therefore
 sonames do not change.
 
 Minor versions are incremented to indicate the release of a new ABI compatible
-DPDK release, typically the DPDK quarterly releases. An example of this, might
-be that ``librte_eal.so.21.1`` would indicate the first ABI compatible DPDK
-release, following the declaration of the new major ABI version ``21``.
+DPDK release, typically the DPDK quarterly releases. For example,
+``librte_eal.so.21.1`` indicates the first ABI compatible DPDK
+release following the declaration of the new major ABI version ``21``.
 
 An ABI version is supported in all new releases until the next major ABI version
-is declared. When changing the major ABI version, the release notes will detail
+is declared. When changing the major ABI version, the release notes detail
 all ABI changes.
 
 .. _figure_abi_stability_policy:
@@ -116,37 +114,37 @@ all ABI changes.
 ABI Changes
 ~~~~~~~~~~~
 
-The ABI may still change after the declaration of a major ABI version, that is
-new APIs may be still added or existing APIs may be modified.
+The ABI may still change after declaring a major ABI version—new APIs may be
+added or existing APIs modified.
 
 .. Warning::
 
-   Note that, this policy details the method by which the ABI may be changed,
+   This policy details the method by which the ABI may be changed,
    with due regard to preserving compatibility and observing deprecation
-   notices. This process however should not be undertaken lightly, as a general
-   rule ABI stability is extremely important for downstream consumers of DPDK.
-   The API should only be changed for significant reasons, such as performance
-   enhancements. API breakages due to changes such as reorganizing public
-   structure fields for aesthetic or readability purposes should be avoided.
+   notices. However, do not undertake this process lightly; as a general
+   rule, ABI stability is extremely important for downstream consumers of DPDK.
+   Change the API only for significant reasons, such as performance
+   enhancements. Avoid API breakages due to changes such as reorganizing public
+   structure fields for aesthetic or readability purposes.
 
 The requirements for changing the ABI are:
 
 #. At least 3 acknowledgments of the need to do so must be made on the
    dpdk.org mailing list.
 
-   - The acknowledgment of the maintainer of the component is mandatory, or if
+   - The component maintainer must acknowledge the change, or if
      no maintainer is available for the component, the tree/sub-tree maintainer
      for that component must acknowledge the ABI change instead.
 
-   - The acknowledgment of three members of the technical board, as delegates
-     of the `technical board <https://core.dpdk.org/techboard/>`_ acknowledging
-     the need for the ABI change, is also mandatory.
+   - Three members of the technical board, as delegates
+     of the `technical board <https://core.dpdk.org/techboard/>`_, must also
+     acknowledge the need for the ABI change.
 
-   - It is also recommended that acknowledgments from different "areas of
-     interest" be sought for each deprecation, for example: from NIC vendors,
+   - Seek acknowledgments from different "areas of
+     interest" for each deprecation, for example: from NIC vendors,
      CPU vendors, end-users, etc.
 
-#. Backward compatibility with the major ABI version must be maintained through
+#. Maintain backward compatibility with the major ABI version through
    :ref:`abi_versioning`, with :ref:`forward-only <forward-only>` compatibility
    offered for any ABI changes that are indicated to be part of the next ABI
    version.
@@ -159,7 +157,7 @@ The requirements for changing the ABI are:
      and Libraries <experimental_apis>`.
 
    - In situations in which an ``experimental`` symbol has been stable for some
-     time. When promoting the symbol to become part of the next ABI version, the
+     time, when promoting the symbol to become part of the next ABI version, the
      maintainer may choose to provide an alias to the ``experimental`` tag, so
      as not to break consuming applications.
 
@@ -167,56 +165,56 @@ The requirements for changing the ABI are:
    API becomes non-experimental, then the old one is marked with
    ``__rte_deprecated``.
 
-    - The deprecated API should follow the notification process to be removed,
-      see  :ref:`deprecation_notices`.
+    - The deprecated API should follow the notification process to be removed;
+      see :ref:`deprecation_notices`.
 
     - At the declaration of the next major ABI version, those ABI changes then
       become a formal part of the new ABI and the requirement to preserve ABI
-      compatibility with the last major ABI version is then dropped.
+      compatibility with the last major ABI version is dropped.
 
-    - The responsibility for removing redundant ABI compatibility code rests
-      with the original contributor of the ABI changes, failing that, then with
-      the contributor's company and then finally with the maintainer.
+    - The original contributor of the ABI changes is responsible for removing
+      redundant ABI compatibility code; failing that, the contributor's company,
+      and then finally the maintainer.
 
 .. _forward-only:
 
 .. Note::
 
-   Note that forward-only compatibility is offered for those changes made
+   Forward-only compatibility is offered for changes made
    between major ABI versions. As a library's soname can only describe
    compatibility with the last major ABI version, until the next major ABI
-   version is declared, these changes therefore cannot be resolved as a runtime
-   dependency through the soname. Therefore any application wishing to make use
-   of these ABI changes can only ensure that its runtime dependencies are met
+   version is declared, these changes cannot be resolved as a runtime
+   dependency through the soname. Therefore, any application wishing to use
+   these ABI changes can only ensure that its runtime dependencies are met
    through Operating System package versioning.
 
 .. _hw_rqmts:
 
 .. Note::
 
-   Updates to the minimum hardware requirements, which drop support for hardware
-   which was previously supported, should be treated as an ABI change, and
+   Treat updates to the minimum hardware requirements, which drop support for
+   previously supported hardware, as an ABI change, and
    follow the relevant deprecation policy procedures as above: 3 acks, technical
-   board approval and announcement at least one release in advance.
+   board approval, and announcement at least one release in advance.
 
 .. _abi_breakages:
 
 ABI Breakages
 ~~~~~~~~~~~~~
 
-For those ABI changes that are too significant to reasonably maintain multiple
-symbol versions, there is an amended process. In these cases, ABIs may be
-updated without the requirement of backward compatibility being provided. These
-changes must follow the same process :ref:`described above <abi_changes>` as non-breaking
-changes, however with the following additional requirements:
+An amended process exists for ABI changes too significant to reasonably maintain
+multiple symbol versions. In these cases, ABIs may be updated without providing
+backward compatibility. These changes must follow the same process
+:ref:`described above <abi_changes>` as non-breaking changes, with the following
+additional requirements:
 
 #. ABI breaking changes (including an alternative map file) can be included with
-   deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option, to provide
-   more details about oncoming changes. ``RTE_NEXT_ABI`` wrapper will be removed
+   the deprecation notice, wrapped by the ``RTE_NEXT_ABI`` option, to provide
+   more details about upcoming changes. The ``RTE_NEXT_ABI`` wrapper is removed
    at the declaration of the next major ABI version.
 
-#. Once approved, and after the deprecation notice has been observed these
-   changes will form part of the next declared major ABI version.
+#. Once approved, and after the deprecation notice has been observed, these
+   changes form part of the next declared major ABI version.
 
 Examples of ABI Changes
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -224,7 +222,7 @@ Examples of ABI Changes
 The following are examples of allowable ABI changes occurring between
 declarations of major ABI versions.
 
-* DPDK 20.11 release defines the function ``rte_foo()`` ; ``rte_foo()``
+* DPDK 20.11 release defines the function ``rte_foo()``; ``rte_foo()``
   is part of the major ABI version ``21``.
 
 * DPDK 21.02 release defines a new function ``rte_foo(uint8_t bar)``.
@@ -235,23 +233,23 @@ declarations of major ABI versions.
     number of releases, as described in the section :ref:`experimental_apis`.
 
   - Once ``rte_foo(uint8_t bar)`` becomes non-experimental, ``rte_foo()`` is
-    declared as ``__rte_deprecated`` and an deprecation notice is provided.
+    declared as ``__rte_deprecated`` and a deprecation notice is provided.
 
-* DPDK 20.11 is not re-released to include ``rte_foo(uint8_t bar)``, the new
+* DPDK 20.11 is not re-released to include ``rte_foo(uint8_t bar)``; the new
   version of ``rte_foo`` only exists from DPDK 21.02 onwards as described in the
   :ref:`note on forward-only compatibility<forward-only>`.
 
 * DPDK 21.02 release defines the experimental function ``__rte_experimental
   rte_baz()``. This function may or may not exist in the DPDK 21.05 release.
 
-* An application ``dPacket`` wishes to use ``rte_foo(uint8_t bar)``, before the
+* An application ``dPacket`` wishes to use ``rte_foo(uint8_t bar)`` before the
   declaration of the DPDK ``22`` major ABI version. The application can only
   ensure its runtime dependencies are met by specifying ``DPDK (>= 21.2)`` as
   an explicit package dependency, as the soname can only indicate the
   supported major ABI version.
 
 * At the release of DPDK 21.11, the function ``rte_foo(uint8_t bar)`` becomes
-  formally part of then new major ABI version DPDK ``22`` and ``rte_foo()`` may be
+  formally part of the new major ABI version DPDK ``22`` and ``rte_foo()`` may be
   removed.
 
 .. _deprecation_notices:
@@ -259,19 +257,19 @@ declarations of major ABI versions.
 Examples of Deprecation Notices
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following are some examples of ABI deprecation notices which would be
-added to the Release Notes:
+The following are some examples of ABI deprecation notices to add
+to the Release Notes:
 
 * The Macro ``#RTE_FOO`` is deprecated and will be removed with ABI version
   22, to be replaced with the inline function ``rte_foo()``.
 
 * The function ``rte_mbuf_grok()`` has been updated to include a new parameter
-  in version 21.2. Backwards compatibility will be maintained for this function
+  in version 21.2. Backward compatibility will be maintained for this function
   until the release of the new DPDK major ABI version 22, in DPDK version
   21.11.
 
 * The members of ``struct rte_foo`` have been reorganized in DPDK 21.02 for
-  performance reasons. Existing binary applications will have backwards
+  performance reasons. Existing binary applications will have backward
   compatibility in release 21.02, while newly built binaries will need to
   reference the new structure variant ``struct rte_foo2``. Compatibility will be
   removed in release 21.11, and all applications will require updating and
@@ -280,7 +278,7 @@ added to the Release Notes:
 
 * Significant ABI changes are planned for the ``librte_dostuff`` library. The
   upcoming release 21.02 will not contain these changes, but release 21.11 will,
-  and no backwards compatibility is planned due to the extensive nature of
+  and no backward compatibility is planned due to the extensive nature of
   these changes. Binaries using this library built prior to ABI version 22 will
   require updating and recompilation.
 
@@ -297,11 +295,11 @@ This is commonly known as the *ABI breakage window*,
 and some amended rules apply during this cycle:
 
  * The requirement to preserve compatibility with the previous major ABI
-   version, as described in the section :ref:`abi_changes` does not apply.
- * Contributors of compatibility preserving code in previous releases,
+   version, as described in the section :ref:`abi_changes`, does not apply.
+ * Contributors of compatibility preserving code in previous releases
    are now required to remove this compatibility code,
    as described in the section :ref:`abi_changes`.
- * Symbol versioning references to the old ABI version are updated
+ * Update symbol versioning references to the old ABI version
    to reference the new ABI version,
    as described in the section :ref:`deprecating_entire_abi`.
  * Contributors of aliases to experimental in previous releases,
@@ -309,9 +307,9 @@ and some amended rules apply during this cycle:
    are now required to remove these aliases.
  * Finally, the *ABI breakage window* is *not* permission to circumvent
    the other aspects of the procedures to make ABI changes
-   described in :ref:`abi_changes`, that is, 3 ACKs of the requirement
+   described in :ref:`abi_changes`; that is, 3 ACKs of the requirement
    to break the ABI and the observance of a deprecation notice
-   are still considered mandatory.
+   are still mandatory.
 
 .. _experimental_apis:
 
@@ -324,31 +322,31 @@ APIs
 APIs marked as ``experimental`` are not considered part of an ABI version and
 may be changed or removed without prior notice. Since changes to APIs are most likely
 immediately after their introduction, as users begin to take advantage of those
-new APIs and start finding issues with them, new DPDK APIs will be automatically
+new APIs and start finding issues with them, new DPDK APIs are automatically
 marked as ``experimental`` to allow for a period of stabilization before they
 become part of a tracked ABI version.
 
-Note that marking an API as experimental is a multi step process.
-To mark an API as experimental, the symbols which are desired to be exported
-must be annotated with a RTE_EXPORT_EXPERIMENTAL_SYMBOL call in the corresponding libraries'
+Note that marking an API as experimental is a multi-step process.
+To mark an API as experimental, annotate the symbols to be exported
+with a RTE_EXPORT_EXPERIMENTAL_SYMBOL call in the corresponding libraries'
 sources.
-Experimental symbols must be commented so that it is clear in which DPDK
+Comment experimental symbols so that it is clear in which DPDK
 version they were introduced.
 
-Secondly, the corresponding prototypes of those exported functions (in the
-development header files), must be marked with the ``__rte_experimental`` tag
+Secondly, mark the corresponding prototypes of those exported functions (in the
+development header files) with the ``__rte_experimental`` tag
 (see ``rte_compat.h``).
 
 In addition to tagging the code with ``__rte_experimental``,
 the doxygen markup must also contain the EXPERIMENTAL string,
 and the MAINTAINERS file should note the EXPERIMENTAL libraries.
 
-For removing the experimental tag associated with an API, deprecation notice is
-not required. Though, an API should remain in experimental state for at least
-one release. Thereafter, the normal process of posting patch for review to
+For removing the experimental tag associated with an API, a deprecation notice is
+not required. However, an API should remain in experimental state for at least
+one release. Thereafter, the normal process of posting a patch for review to the
 mailing list can be followed.
 
-After the experimental tag has been formally removed, a tree/sub-tree maintainer
+After formally removing the experimental tag, a tree/sub-tree maintainer
 may choose to offer an alias to the experimental tag so as not to break
 applications using the symbol. The alias is then dropped at the declaration of
 next major ABI version.
@@ -363,16 +361,16 @@ All functions in such libraries may be changed or removed without prior notice.
 Promotion to stable
 ~~~~~~~~~~~~~~~~~~~
 
-An API's ``experimental`` status should be reviewed annually,
+Review an API's ``experimental`` status annually,
 by both the maintainer and/or the original contributor.
-Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
-once a maintainer has become satisfied that the API is mature
+Ordinarily, promote APIs marked as ``experimental`` to the stable ABI
+once a maintainer is satisfied that the API is mature
 and is unlikely to change.
 
 In exceptional circumstances, should an API still be classified
 as ``experimental`` after two years
-and is without any prospect of becoming part of the stable API.
-The API will then become a candidate for removal,
+and be without any prospect of becoming part of the stable API,
+the API will then become a candidate for removal,
 to avoid the accumulation of abandoned symbols.
 
 Should an ABI change, usually due to a direct change to the API's signature,
-- 
2.51.0

[PATCH v2 03/12] doc: improve coding style guide readability

[Stephen Hemminger]

Improve the coding style documentation
- Converting passive voice to active voice
- Using imperative mood for instructions
- Simplifying redundant phrasing
- Clarifying guidance on bool usage in structures

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/coding_style.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst
index 243a3c2959..898c84ceec 100644
--- a/doc/guides/contributing/coding_style.rst
+++ b/doc/guides/contributing/coding_style.rst
@@ -9,8 +9,8 @@ DPDK Coding Style
 Description
 -----------
 
-This document specifies the preferred style for source files in the DPDK source tree.
-It is based on the Linux Kernel coding guidelines and the FreeBSD 7.2 Kernel Developer's Manual (see man style(9)), but was heavily modified for the needs of the DPDK.
+This document specifies the preferred style for source files in the DPDK source tree,
+based on the Linux Kernel coding guidelines and the FreeBSD 7.2 Kernel Developer's Manual (see man style(9)), but was heavily modified for the needs of the DPDK.
 
 General Guidelines
 ------------------
@@ -95,7 +95,7 @@ Example:
 Header File Guards
 ~~~~~~~~~~~~~~~~~~
 
-Headers should be protected against multiple inclusion with the usual:
+Protect headers against multiple inclusion with the usual:
 
 .. code-block:: c
 
@@ -293,7 +293,7 @@ Structure Declarations
 * In general, when declaring variables in new structures, declare them sorted by use, then by size (largest to smallest), and then in alphabetical order.
   Sorting by use means that commonly used variables are used together and that the structure layout makes logical sense.
   Ordering by size then ensures that as little padding is added to the structure as possible.
-* For existing structures, additions to structures should be added to the end so for backward compatibility reasons.
+* For existing structures, add new members to the end for backward compatibility.
 * Each structure element gets its own line.
 * Try to make the structure readable by aligning the member names using spaces as shown below.
 * Names following extremely long types, which therefore cannot be easily aligned with the rest, should be separated by a single space.
@@ -308,14 +308,14 @@ Structure Declarations
  };
 
 
-* Major structures should be declared at the top of the file in which they are used, or in separate header files if they are used in multiple source files.
+* Declare major structures at the top of the file where they are used, or in separate header files if they are used in multiple source files.
 * Use of the structures should be by separate variable declarations and those declarations must be extern if they are declared in a header file.
 * Externally visible structure definitions should have the structure name prefixed by ``rte_`` to avoid namespace collisions.
 
 .. note::
 
-    Uses of ``bool`` in structures are not preferred as is wastes space and
-    it's also not clear as to what type size the bool is. A preferred use of
+    Avoid using ``bool`` in structures because it wastes space and
+    the type size is unclear. A preferred use of
     ``bool`` is mainly as a return type from functions that return true/false,
     and maybe local variable functions.
 
@@ -584,7 +584,7 @@ C Function Definition, Declaration and Use
 Prototypes
 ~~~~~~~~~~
 
-* It is recommended (and generally required by the compiler) that all non-static functions are prototyped somewhere.
+* Prototype all non-static functions (the compiler generally requires this).
 * Functions local to one source module should be declared static, and should not be prototyped unless absolutely necessary.
 * Functions used from other parts of code (external API) must be prototyped in the relevant include file.
 * Function prototypes should be listed in a logical order, preferably alphabetical unless there is a compelling reason to use a different ordering.
@@ -747,7 +747,7 @@ Static Variables and Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * All functions and variables that are local to a file must be declared as ``static`` because it can often help the compiler to do some optimizations (such as, inlining the code).
-* Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file.
+* Declare functions that should be inlined as ``static inline`` and can be defined in a .c or a .h file.
 
 .. note::
 	Static functions defined in a header file must be declared as ``static inline`` in order to prevent compiler warnings about the function being unused.
@@ -755,7 +755,7 @@ Static Variables and Functions
 Const Attribute
 ~~~~~~~~~~~~~~~
 
-The ``const`` attribute should be used as often as possible when a variable is read-only.
+Use the ``const`` attribute as often as possible when a variable is read-only.
 
 Inline ASM in C code
 ~~~~~~~~~~~~~~~~~~~~
-- 
2.51.0

[PATCH v2 04/12] doc: improve documentation guidelines style

[Stephen Hemminger]

Improve readability of the documentation guidelines
- Using active voice throughout
- Converting "should be" constructions to imperative mood
- Fixing minor grammar issues in Doxygen guidance

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/documentation.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 338254cf30..c6009cbc12 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -39,7 +39,7 @@ The main directories that contain files related to documentation are shown below
        |-- ...
 
 
-The API documentation is built from `Doxygen <http://www.doxygen.nl>`_ comments in the header files.
+Doxygen comments in header files generate the API documentation. These are built from `Doxygen <http://www.doxygen.nl>`_ comments in the header files.
 These files are mainly in the ``lib/*`` directories although some of the Poll Mode Drivers in ``drivers/net``
 are also documented with Doxygen.
 
@@ -84,7 +84,7 @@ added to by the developer.
   The API documentation explains how to use the public DPDK functions.
   The `API index page <https://doc.dpdk.org/api/>`_ shows the generated API documentation with related groups of functions.
 
-  The API documentation should be updated via Doxygen comments when new functions are added.
+  Update API documentation via Doxygen comments when adding new functions.
 
 * **Getting Started Guides**
 
@@ -606,7 +606,7 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati
   It isn't necessary to explicitly name each file since the configuration matches all ``rte_*.h`` files in the directory.
 
 * Use proper capitalization and punctuation in the Doxygen comments since they will become sentences in the documentation.
-  This in particular applies to single line comments, which is the case the is most often forgotten.
+  This applies particularly to single-line comments, which developers most often forget.
 
 * Use ``@`` style Doxygen commands instead of ``\`` style commands.
 
-- 
2.51.0

[PATCH v2 05/12] doc: improve Linux uAPI header documentation

[Stephen Hemminger]

Improve clarity of the Linux uAPI header documentation
- Converting passive voice to active voice
- Simplifying sentence structure
- Making instructions more direct
- Removing redundant wording

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/linux_uapi.rst | 40 ++++++++++++--------------
 1 file changed, 19 insertions(+), 21 deletions(-)

diff --git a/doc/guides/contributing/linux_uapi.rst b/doc/guides/contributing/linux_uapi.rst
index a1bc0ba604..b28ebc4663 100644
--- a/doc/guides/contributing/linux_uapi.rst
+++ b/doc/guides/contributing/linux_uapi.rst
@@ -7,36 +7,34 @@ Linux uAPI header files
 Rationale
 ---------
 
-The system a DPDK library or driver is built on is not necessarily running the
-same Kernel version than the system that will run it.
-Importing Linux Kernel uAPI headers enable to build features that are not
-supported yet by the build system.
+The build system may run a different kernel version than the deployment target.
+To support features unavailable in the build system's kernel, import Linux kernel uAPI headers.
 
-For example, the build system runs upstream Kernel v5.19 and we would like to
-build a VDUSE application that will use VDUSE_IOTLB_GET_INFO ioctl() introduced
-in Linux Kernel v6.0.
+For example, if the build system runs upstream Kernel v5.19, but you need to build a VDUSE application
+that uses the VDUSE_IOTLB_GET_INFO ioctl introduced in Kernel v6.0, importing the relevant uAPI headers enables this.
+
+The Linux kernel's syscall license exception permits the inclusion of unmodified uAPI header files in such cases.
 
 `Linux Kernel licence exception regarding syscalls
 <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/LICENSES/exceptions/Linux-syscall-note>`_
-enable importing unmodified Linux Kernel uAPI header files.
+enables importing unmodified Linux Kernel uAPI header files.
 
 Importing or updating an uAPI header file
 -----------------------------------------
 
-In order to ensure the imported uAPI headers are both unmodified and from a
-released version of the linux Kernel, a helper script is made available and
-MUST be used.
+To ensure that imported uAPI headers are unmodified and sourced from an official Linux
+kernel release, a helper script is provided and must be used.
 Below is an example to import ``linux/vduse.h`` file from Linux ``v6.10``:
 
 .. code-block:: console
 
    devtools/linux-uapi.sh -i linux/vduse.h -u v6.10
 
-Once imported, the header files should be committed without any other change.
-Note that all the imported headers will be updated to the requested version.
+Once imported, commit header files without any modifications. Note that all imported
+headers are updated to match the specified kernel version.
 
-Updating imported headers to a newer released version should only be done on
-a need basis, it can be achieved using the same script:
+Perform updates to a newer released version only when necessary, using
+the same helper script.
 
 .. code-block:: console
 
@@ -44,8 +42,8 @@ a need basis, it can be achieved using the same script:
 
 The commit message should reflect why updating the headers is necessary.
 
-Once committed, user can check headers are valid by using the same Linux
-uAPI script using the check option:
+Once committed, check that headers are valid using the same Linux
+uAPI script with the check option:
 
 .. code-block:: console
 
@@ -60,13 +58,13 @@ Note that all the linux-uapi.sh script options can be combined. For example:
 Header inclusion into library or driver
 ---------------------------------------
 
-The library or driver willing to make use of imported uAPI headers needs to
-explicitly include the header file with ``uapi/`` prefix in C files.
+Libraries or drivers that rely on imported uAPI headers must explicitly include
+the relevant header using the ``uapi/`` prefix in their C source files.
 
 This inclusion must be done before any header external to DPDK is included,
-to prevent inclusion of this system uAPI header in any of those external headers.
+to prevent inclusion of the system uAPI header in any of those external headers.
 
-For example to include VDUSE uAPI:
+For example, to include VDUSE uAPI:
 
 .. code-block:: c
 
-- 
2.51.0

[PATCH v2 06/12] doc: improve new driver guide readability

[Stephen Hemminger]

Improve the new driver contribution guide
- Converting passive voice to active voice
- Using imperative mood for recommendations
- Removing "We recommend" and similar phrases
- Simplifying wordy constructions

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/new_driver.rst | 62 +++++++++++++-------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/doc/guides/contributing/new_driver.rst b/doc/guides/contributing/new_driver.rst
index 555e875329..23d986d941 100644
--- a/doc/guides/contributing/new_driver.rst
+++ b/doc/guides/contributing/new_driver.rst
@@ -6,10 +6,10 @@ Adding a New Driver
 ===================
 
 The DPDK project continuously grows its ecosystem by adding support for new devices.
-This document is designed to assist contributors in creating DPDK drivers,
+This document assists contributors in creating DPDK drivers,
 also known as Poll Mode Drivers (PMD).
 
-By having public support for a device, we can ensure accessibility across various
+By having public support for a device, we ensure accessibility across various
 operating systems and guarantee community maintenance in future releases.
 If a new device is similar to a device already supported by an existing driver,
 it is more efficient to update the existing driver.
@@ -20,8 +20,8 @@ Here are our best practice recommendations for creating a new driver.
 Early Engagement with the Community
 -----------------------------------
 
-When creating a new driver, we highly recommend engaging with the DPDK
-community early instead of waiting the work to mature.
+When creating a new driver, engage with the DPDK community early
+rather than waiting for the work to mature.
 
 These public discussions help align development of your driver with DPDK expectations.
 You may submit a roadmap before the release to inform the community of your plans.
@@ -29,31 +29,31 @@ Additionally, sending a Request For Comments (RFC) early in the release cycle,
 or even during the prior release, is advisable.
 
 DPDK is mainly consumed via Long Term Support (LTS) releases.
-It is common to target a new PMD to a LTS release. For this,
-it is suggested to start upstreaming at least one release before a LTS release.
+It is common to target a new PMD to an LTS release. For this,
+start upstreaming at least one release before an LTS release.
 
 
 Progressive Work
 ----------------
 
-To continually progress your work, we recommend planning
+To continually progress your work, plan
 for incremental upstreaming across multiple patch series or releases.
 
-It's important to prioritize quality of the driver over upstreaming
+Prioritize quality of the driver over upstreaming
 in a single release or single patch series.
 
 
 Finalizing
 ----------
 
-Once the driver has been upstreamed,
-the author has a responsibility to the community to maintain it.
+Once the driver is upstreamed,
+the author is responsible for maintaining it.
 
 This includes the public test report.
 Authors must send a public test report after the first upstreaming of the PMD.
 The same public test procedure may be reproduced regularly per release.
 
-After the PMD is upstreamed, the author should send a patch to update
+After the PMD is upstreamed, send a patch to update
 `the website <https://core.dpdk.org/supported/>`_
 with the name of the new PMD and supported devices via the
 `DPDK web mailing list <https://mails.dpdk.org/listinfo/web>`_.
@@ -64,7 +64,7 @@ For more information about the role of maintainers, see :doc:`patches`.
 Splitting into Patches
 ----------------------
 
-We recommend that drivers are split into patches,
+Split drivers into patches
 so that each patch represents a single feature.
 If the driver code is already developed, it may be challenging to split.
 However, there are many benefits to doing so.
@@ -73,17 +73,17 @@ Splitting patches makes it easier to understand a feature
 and clarifies the list of components/files that compose that specific feature.
 
 It also enables the ability to track
-from the source code to the feature it is enabled for,
-and helps users to understand the reasoning and intention of implementation.
+from the source code to the feature it enables,
+and helps users understand the reasoning and intention of implementation.
 This kind of tracing is regularly required for defect resolution and refactoring.
 
 Another benefit of splitting the codebase per feature is that
 it highlights unnecessary or irrelevant code,
 as any code not belonging to any specific feature becomes obvious.
 
-Git bisect is also more useful if patches are split per patch.
+Git bisect is also more useful if patches are split per feature.
 
-The split should focus on logical features rather than file-based divisions.
+Focus the split on logical features rather than file-based divisions.
 
 Each patch in the series must compile without errors
 and should maintain functionality.
@@ -92,20 +92,20 @@ Enable the build as early as possible within the series
 to facilitate continuous integration and testing.
 This approach ensures a clear and manageable development process.
 
-We suggest splitting patches following this approach:
+Split patches following this approach:
 
-* Each patch should be organized logically as a new feature.
+* Organize each patch logically as a new feature.
 * Run test tools per patch (See :ref:`tool_list`).
 * Update relevant documentation and `<driver>.ini` file with each patch.
 
-The following order in the patch series is as suggested below.
+The following order in the patch series is suggested.
 
 The first patch should have the driver's skeleton which should include:
 
 * Maintainers file update
 * Driver documentation
 * Document must have links to official product documentation web page
-* The new document should be added into the index (`index.rst`)
+* Add the new document to the index (`index.rst`)
 * Initial `<driver>.ini` file
 * Release notes announcement for the new driver
 
@@ -152,10 +152,10 @@ Time synchronization, PTP
 Performance documentation
 ================================  ================================
 
-After all features are enabled,
+After enabling all features,
 if there is remaining base code that is not upstreamed,
-they can be upstreamed at the end of the patch series.
-However, we recommend these patches are still split into logical groups.
+upstream it at the end of the patch series.
+However, still split these patches into logical groups.
 
 
 Additional Suggestions
@@ -185,12 +185,12 @@ Remember to do the following:
 Dependencies
 ------------
 
-At times, drivers may have dependencies to external software.
-For driver dependencies, same DPDK rules for dependencies applies.
-Dependencies should be publicly and freely available,
-drivers which depend on non-available components will not be accepted.
+At times, drivers may have dependencies on external software.
+For driver dependencies, the same DPDK rules for dependencies apply.
+Dependencies should be publicly and freely available;
+drivers that depend on unavailable components will not be accepted.
 If the required dependency is not yet publicly available,
-then wait to submit the driver until the dependent library is available.
+wait to submit the driver until the dependent library is available.
 
 
 .. _tool_list:
@@ -199,10 +199,10 @@ Test Tools
 ----------
 
 Build and check the driver's documentation.
-Make sure there are no warnings,
-and driver shows up in the relevant index page.
+Ensure there are no warnings
+and the driver shows up in the relevant index page.
 
-Be sure to run the following test tools per patch in a patch series:
+Run the following test tools per patch in a patch series:
 
 * `checkpatches.sh`
 * `check-git-log.sh`
-- 
2.51.0

[PATCH v2 07/12] doc: improve new library guide style

[Stephen Hemminger]

Improve the new library contribution guide
- Converting passive voice to active voice
- Simplifying sentence structure
- Using more direct language

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/new_library.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/doc/guides/contributing/new_library.rst b/doc/guides/contributing/new_library.rst
index 99890beb29..25237b349f 100644
--- a/doc/guides/contributing/new_library.rst
+++ b/doc/guides/contributing/new_library.rst
@@ -10,15 +10,15 @@ Process for approval in principle
 Rationale
 ~~~~~~~~~
 
-Adding a new library to DPDK with proper RFC and then full patch-sets is a significant work.
-In order to save effort, developers should get an early approval in principle,
-or an early feedback in case the library is not suitable for various reasons.
+Adding a new library to DPDK with proper RFC and then full patch-sets requires significant effort.
+To save effort, developers should seek early approval in principle,
+or early feedback if the library is unsuitable for various reasons.
 
 Process
 ~~~~~~~
 
-#. When a contributor would like to add a new library to DPDK code base,
-   the contributor must send the following items to DPDK mailing list
+#. When a contributor would like to add a new library to the DPDK code base,
+   the contributor must send the following items to the DPDK mailing list
    for Technical Board approval-in-principle.
 
    * Purpose of the library.
@@ -38,13 +38,13 @@ Process
 
    * Any new library dependencies to DPDK.
 
-#. Technical Board to schedule discussion on this in upcoming Technical Board meeting
-   along with author.
+#. Technical Board schedules discussion on this in an upcoming Technical Board meeting
+   along with the author.
    Based on the Technical Board schedule and/or author availability,
    Technical Board may need a maximum of **five** Technical Board meeting slots.
 
 #. Based on mailing list and Technical Board meeting discussions,
-   Technical Board to vote and share the decision in the mailing list.
+   Technical Board votes and shares the decision on the mailing list.
    The decision outcome can be any of the following:
 
    * Approved in principle
@@ -53,5 +53,5 @@ Process
 
 #. Once the Technical Board approves the library in principle,
    it is safe to start working on the implementation.
-   However, the patches will need to meet the usual quality criteria
-   in order to be effectively accepted.
+   However, the patches must meet the usual quality criteria
+   to be effectively accepted.
-- 
2.51.0

[PATCH v2 08/12] doc: improve patch submission guide readability

[Stephen Hemminger]

Improve the patch submission documentation
- Converting passive voice to active voice throughout
- Using imperative mood for instructions
- Reorganizing content with clearer section headers
- Simplifying wordy constructions
- Removing redundant phrases

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/patches.rst | 434 ++++++++++++++--------------
 1 file changed, 224 insertions(+), 210 deletions(-)

diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index 069a18e4ec..129952dc76 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -6,55 +6,53 @@
 Contributing Code to DPDK
 =========================
 
-This document outlines the guidelines for submitting code to DPDK.
+This document provides guidelines for submitting code to DPDK.
 
-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:
+The DPDK development process is loosely based on the Linux Kernel development
+model. Review the Linux kernel's guide:
 `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.
+Many of DPDK's submission guidelines draw from the kernel process,
+and the rationale behind them is often explained in greater depth there.
 
 
 The DPDK Development Process
 ----------------------------
 
-The DPDK development process has the following features:
+The DPDK development process includes the following key elements:
 
-* The code is hosted in a public git repository.
-* There is a mailing list where developers submit patches.
-* There are maintainers for hierarchical components.
-* Patches are reviewed publicly on the mailing list.
-* Successfully reviewed patches are merged to the repository.
-* Patches should be sent to the target repository or sub-tree, see below.
+* The project maintains code in a public Git repository.
+* Developers submit patches via a public mailing list.
+* A hierarchical structure assigns maintainers to different components.
+* The community reviews patches publicly on the mailing list.
+* Maintainers merge reviewed patches into the repository.
+* Contributors should send patches to the target repository or sub-tree (see below for details).
 
 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/>`_
+Contributors must `register for the mailing list <https://mails.dpdk.org/listinfo/dev>`_ to submit patches.
+Register for DPDK `Patchwork <https://patches.dpdk.org/project/dpdk/list/>`_ as well.
 
-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.
+If you use GitHub, pushing to a branch triggers GitHub Actions,
+which builds your changes and runs unit tests and ABI checks.
 
-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.
+Contributing to DPDK requires a basic understanding of the Git version control system.
+For more information, refer to the `Pro Git Book <http://www.git-scm.com/book/>`_.
 
 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 <http://spdx.org/>`_.
+DPDK uses the Open Source BSD-3-Clause license for its core libraries and
+drivers. Kernel components use the GPL-2.0 license.
+To identify licenses in source files, DPDK follows the SPDX standard
+developed by the Linux Foundation `SPDX project <http://spdx.org/>`_.
 
-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.
+Use the SPDX tag on the first line of the file.
+For *#!* scripts, place the SPDX tag on the second line.
 
-For example, to label a file as subject to the BSD-3-Clause license,
-the following text would be used:
+For BSD-3-Clause:
 
 ``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:
+For dual-licensing with BSD-3-Clause and GPL-2.0 (e.g., shared kernel/user-space code):
 
 ``SPDX-License-Identifier: (BSD-3-Clause OR GPL-2.0)``
 
@@ -63,11 +61,11 @@ Refer to ``licenses/README`` for more details.
 Maintainers and Sub-trees
 -------------------------
 
-The DPDK maintenance hierarchy is divided into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
+The DPDK maintenance hierarchy divides into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``.
 
-There are maintainers for the trees and for components within the tree.
+Maintainers exist for the trees and for components within the tree.
 
-Trees and maintainers are listed in the ``MAINTAINERS`` file. For example::
+The ``MAINTAINERS`` file lists trees and maintainers. For example::
 
     Crypto Drivers
     --------------
@@ -85,45 +83,49 @@ Where:
 * ``T`` is a repository tree.
 * ``F`` is a maintained file or directory.
 
-Additional details are given in the ``MAINTAINERS`` file.
+The ``MAINTAINERS`` file contains additional details.
 
-The role of the component maintainers is to:
+Component maintainers are responsible for:
 
-* Review patches for the component or delegate the review.
-  The review should be done, ideally, within 1 week of submission to the mailing list.
-* Add an ``acked-by`` to patches, or patchsets, that are ready for committing to a tree.
-* Reply to questions asked about the component.
+* Reviewing patches related to their component or delegating review to others.
+  Ideally, complete reviews within one week of mailing list submission.
+* Acknowledging patches by adding an ``acked-by`` tag to those deemed ready for merging.
+* Responding to questions regarding the component and offering guidance when needed.
 
-Component maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
-Maintainers should have demonstrated a reasonable level of contributions or reviews to the component area.
-The maintainer should be confirmed by an ``ack`` from an established contributor.
-There can be more than one component maintainer if desired.
+Add or remove maintainers by submitting a patch to the ``MAINTAINERS`` file.
+New maintainers should have demonstrated consistent contributions or reviews to the component area.
+An established contributor must confirm their addition with an ``ack``.
+A single component may have multiple maintainers if needed.
 
-The role of the tree maintainers is to:
+Tree Maintainer Responsibilities:
 
-* Maintain the overall quality of their tree.
-  This can entail additional review, compilation checks or other tests deemed necessary by the maintainer.
-* Commit patches that have been reviewed by component maintainers and/or other contributors.
-  The tree maintainer should determine if patches have been reviewed sufficiently.
-* Ensure that patches are reviewed in a timely manner.
-* Prepare the tree for integration.
-* Ensure that there is a designated back-up maintainer and coordinate a handover for periods where the
-  tree maintainer can't perform their role.
+Tree maintainers ensure the overall quality and integrity of their tree.
+Their duties include:
 
-Tree maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file.
-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.
-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.
+* Conducting additional reviews, compilation checks, or other tests as needed.
+* Committing patches that component maintainers or other contributors have sufficiently reviewed.
+* Ensuring timely review of submitted patches.
+* Preparing the tree for integration.
+* Appointing a designated backup maintainer and coordinating handovers when unavailable.
 
-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.
+Maintainer Changes:
+
+Add or remove tree maintainers by submitting a patch to the MAINTAINERS file.
+Proposals must justify the creation of a new sub-tree and demonstrate significant contribution
+to the relevant area. An existing tree maintainer must ack the proposal.
+
+Escalate disputes regarding trees or maintainers to the Technical Board.
+
+Backup Maintainers:
+
+* Choose the main tree's backup maintainer from among existing sub-tree maintainers.
+* Choose a sub-tree's backup from the component maintainers within that sub-tree.
 
 
 Getting the Source Code
 -----------------------
 
-The source code can be cloned using either of the following:
+Clone the source code using either of the following:
 
 main repository::
 
@@ -135,63 +137,72 @@ sub-repositories (`list <https://git.dpdk.org/next>`_)::
     git clone git://dpdk.org/next/dpdk-next-*
     git clone https://dpdk.org/git/next/dpdk-next-*
 
-Make your Changes
------------------
+Make Changes
+------------
 
-Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines and requirements:
+After cloning the DPDK repository, make your planned changes while following
+these key guidelines and requirements:
 
 * Follow the :ref:`coding_style` guidelines.
 
 * If you are a new contributor, or if your mail address changed,
   you may update the ``.mailmap`` file.
-  Otherwise the new name or address will be added by a maintainer.
-  Keeping this file up-to-date will help when someone wants to contact you
-  about the changes you contributed to.
+  Otherwise a maintainer will add the new name or address.
+  Keeping this file up-to-date helps when someone wants to contact you
+  about the changes you contributed.
+
+* If you add new files or directories, add your name to the ``MAINTAINERS`` file.
 
-* If you add new files or directories you should add your name to the ``MAINTAINERS`` file.
+PMD Submissions
+~~~~~~~~~~~~~~~
 
-* Initial submission of new PMDs should be prepared against a corresponding repo.
+* Prepare initial submissions of new PMDs against the corresponding repo.
 
-  * Thus, for example, initial submission of a new network PMD should be
-    prepared against dpdk-next-net repo.
+  * For example, prepare initial submission of a new network PMD
+    against the dpdk-next-net repo.
 
-  * Likewise, initial submission of a new crypto or compression PMD should be
-    prepared against dpdk-next-crypto repo.
+  * Likewise, prepare initial submission of a new crypto or compression PMD
+    against the dpdk-next-crypto repo.
 
   * For other PMDs and more info, refer to the ``MAINTAINERS`` file.
 
-* New external functions should be exported.
+* Export new external functions.
   See the :doc:`ABI policy <abi_policy>` and :ref:`ABI versioning <abi_versioning>`
   guides.
 
-* Any new API function should be used in ``/app`` test directory.
+API and ABI Guidelines
+~~~~~~~~~~~~~~~~~~~~~~
+
+* Use any new API function in the ``/app`` test directory.
 
 * When introducing a new device API, at least one driver should implement it.
 
-* Important changes will require an addition to the release notes in ``doc/guides/rel_notes/``.
+Documentation and Release Notes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Important changes 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.
 
-* Test the compilation works with different targets, compilers and options, see :ref:`contrib_check_compilation`.
+* Test compilation with different targets, compilers, and options; see :ref:`contrib_check_compilation`.
 
-* 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.
+* Do not break compilation between commits with forward dependencies in a patch set.
+  Each commit should compile on its own to allow ``git bisect`` and continuous integration testing.
 
 * 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>`.
 
-* Code and related documentation must be updated atomically in the same patch.
+* Update code and related documentation atomically in the same patch.
 
-Once the changes have been made you should commit them to your local repo.
+Commit your changes to your local repo after making them.
 
-For small changes, that do not require specific explanations, it is better to keep things together in the
-same patch.
-Larger changes that require different explanations should be separated into logical patches in a patchset.
-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.
+Keep small changes that do not require specific explanations in a single patch.
+Separate larger changes that require different explanations into logical patches in a patch set.
+Consider whether the change could be applied without dependencies as a backport
+when deciding whether to split a patch.
 
-As a guide to how patches should be structured run ``git log`` on similar files.
+Run ``git log`` on similar files as a guide to how patches should be structured.
 
 
 Commit Messages: Subject Line
@@ -206,7 +217,7 @@ Here are some guidelines for the summary line:
 
 * The summary line should be lowercase apart from acronyms.
 
-* It should be prefixed with the component name (use git log to check existing components).
+* Prefix with the component name (use git log to check existing components).
   For example::
 
      ixgbe: fix offload config option name
@@ -215,54 +226,54 @@ Here are some guidelines for the summary line:
 
 * Use the imperative of the verb (like instructions to the code base).
 
-* Don't add a period/full stop to the subject line or you will end up two in the patch name: ``dpdk_description..patch``.
+* Do not add a period/full stop to the subject line or you will end up with two in the patch name: ``dpdk_description..patch``.
 
 The actual email subject line should be prefixed by ``[PATCH]`` and the version, if greater than v1,
 for example: ``PATCH v2``.
-The is generally added by ``git send-email`` or ``git format-patch``, see below.
+``git send-email`` or ``git format-patch`` generally adds this prefix; see below.
 
-If you are submitting an RFC draft of a feature you can use ``[RFC]`` instead of ``[PATCH]``.
-An RFC patch doesn't have to be complete.
+If you are submitting an RFC draft of a feature, use ``[RFC]`` instead of ``[PATCH]``.
+An RFC patch does not have to be complete.
 It is intended as a way of getting early feedback.
 
 
 Commit Messages: Body
 ---------------------
 
-Here are some guidelines for the body of a commit message:
+Here are guidelines for the body of a commit message:
 
 * The body of the message should describe the issue being fixed or the feature being added.
-  It is important to provide enough information to allow a reviewer to understand the purpose of the patch.
+  Provide enough information to allow a reviewer to understand the purpose of the patch.
 
-* When the change is obvious the body can be blank, apart from the signoff.
+* When the change is obvious, the body can be blank apart from the signoff.
 
-* The commit message must end with a ``Signed-off-by:`` line which is added using::
+* The commit message must end with a ``Signed-off-by:`` line, added using::
 
       git commit --signoff # or -s
 
-  The purpose of the signoff is explained in the
+  The
   `Developer's Certificate of Origin <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1>`_
-  section of the Linux kernel guidelines.
+  section of the Linux kernel guidelines explains the purpose of the signoff.
 
   .. Note::
 
-     All developers must ensure that they have read and understood the
+     All developers must read and understand the
      Developer's Certificate of Origin section of the documentation prior
      to applying the signoff and submitting a patch.
 
 * The signoff must be a real name and not an alias or nickname.
   More than one signoff is allowed.
 
-* The text of the commit message should be wrapped at 72 characters.
+* Wrap the text of the commit message at 72 characters.
 
-* When fixing a regression, it is required to reference the id of the commit
+* When fixing a regression, 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
+  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\")%nCc: %ae'"
 
-  The output of ``git fixline <SHA>`` must then be added to the commit message::
+  Add the output of ``git fixline <SHA>`` to the commit message::
 
      doc: fix some parameter description
 
@@ -274,12 +285,12 @@ Here are some guidelines for the body of a commit message:
      ---
      Cc: author@example.com
 
-* When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
+* When fixing an error or warning, include the error message and instructions on how to reproduce it.
 
-* Use correct capitalization, punctuation and spelling.
+* Use correct capitalization, punctuation, and spelling.
 
-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
+In addition to the ``Signed-off-by:`` name, 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
@@ -287,7 +298,7 @@ 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,
+It is used as a cloud-based service 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::
@@ -308,7 +319,7 @@ in the body of the commit message. For example::
 `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.
+to effectively track 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::
@@ -327,10 +338,10 @@ For example::
 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>`_
+CC all fix patches to the main branch that are candidates for backporting
+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::
+In the commit message body, insert ``Cc: stable@dpdk.org`` as follows::
 
      doc: fix some parameter description
 
@@ -341,19 +352,19 @@ In the commit message body the Cc: stable@dpdk.org should be inserted as follows
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
 
-For further information on stable contribution you can go to
+For further information on stable contribution, see
 :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
+Sometimes a patch or patch set depends on another one.
+To help the maintainers and automation tasks, document this dependency in the 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::
+Where ``NNNNN`` is the patchwork ID for the patch or series::
 
      doc: fix some parameter description
 
@@ -366,7 +377,7 @@ Where ``NNNNN`` is patchwork ID for patch or series::
 Tag order
 ~~~~~~~~~
 
-There is a pattern indicating how certain tags should relate to each other.
+A pattern indicates how certain tags should relate to each other.
 
 Example of proper tag sequence::
 
@@ -382,22 +393,22 @@ Example of proper tag sequence::
      Reviewed-by:
      Tested-by:
 
-Between first and second tag section there is and empty line.
+An empty line separates the first and second tag sections.
 
-While ``Signed-off-by:`` is an obligatory tag and must exist in each commit,
+While ``Signed-off-by:`` is obligatory and must exist in each commit,
 all other tags are optional.
-Any tag, as long as it is in proper location to other adjacent tags (if present),
+Any tag, as long as it is in proper location relative to other adjacent tags (if present),
 may occur multiple times.
 
-Tags after the first occurrence of ``Signed-off-by:`` shall be laid out
-in a chronological order.
+Place tags after the first occurrence of ``Signed-off-by:``
+in chronological order.
 
 
 Creating Patches
 ----------------
 
-It is possible to send patches directly from git but for new contributors it is recommended to generate the
-patches with ``git format-patch`` and then when everything looks okay, and the patches have been checked, to
+You can send patches directly from git, but for new contributors it is recommended to generate the
+patches with ``git format-patch`` and then, when everything looks okay and the patches have been checked,
 send them with ``git send-email``.
 
 Here are some examples of using ``git format-patch`` to generate patches:
@@ -413,15 +424,15 @@ Here are some examples of using ``git format-patch`` to generate patches:
    # Generate the patches in a directory.
    git format-patch -3 -o ~/patch/
 
-   # Add a cover letter to explain a patchset.
+   # Add a cover letter to explain a patch set.
    git format-patch -3 -o ~/patch/ --cover-letter
 
    # Add a prefix with a version number.
    git format-patch -3 -o ~/patch/ -v 2
 
 
-Cover letters are useful for explaining a patchset and help to generate a logical threading to the patches.
-Smaller notes can be put inline in the patch after the ``---`` separator, for example::
+Cover letters are useful for explaining a patch set and help generate logical threading to the patches.
+Put smaller notes inline in the patch after the ``---`` separator, for example::
 
    Subject: [PATCH] fm10k/base: add FM10420 device ids
 
@@ -438,8 +449,8 @@ Smaller notes can be put inline in the patch after the ``---`` separator, for ex
     2 files changed, 12 insertions(+)
    ...
 
-Version 2 and later of a patchset should also include a short log of the changes so the reviewer knows what has changed.
-This can be added to the cover letter or the annotations.
+Version 2 and later of a patch set should also include a short log of the changes so the reviewer knows what has changed.
+Add this to the cover letter or the annotations.
 For example::
 
    ---
@@ -457,32 +468,32 @@ For example::
 Checking the Patches
 --------------------
 
-Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``devtools``
+Check patches for formatting and syntax issues using the ``checkpatches.sh`` script in the ``devtools``
 directory of the DPDK repo.
-This uses the Linux kernel development tool ``checkpatch.pl`` which  can be obtained by cloning, and periodically,
-updating the Linux kernel sources.
+This uses the Linux kernel development tool ``checkpatch.pl``, which can be obtained by cloning, and periodically
+updating, the Linux kernel sources.
 
-The path to the original Linux script must be set in the environment variable ``DPDK_CHECKPATCH_PATH``.
+Set the path to the original Linux script in the environment variable ``DPDK_CHECKPATCH_PATH``.
 
 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
+Specify a different dictionary path
 in the environment variable ``DPDK_CHECKPATCH_CODESPELL``.
 
-There is a DPDK script to build an adjusted dictionary
+A DPDK script builds 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::
+The development tools load environment variables
+from the following files, in order of preference::
 
    .develconfig
    ~/.config/dpdk/devel.config
    /etc/dpdk/devel.config.
 
-Once the environment variable is set, the script can be run as follows::
+Once the environment variable is set, run the script as follows::
 
    devtools/checkpatches.sh ~/patch/
 
@@ -490,34 +501,34 @@ The script usage is::
 
    checkpatches.sh [-h] [-q] [-v] [-nX|-r range|patch1 [patch2] ...]
 
-Then the git logs should be checked using the ``check-git-log.sh`` script.
+Then check the git logs using the ``check-git-log.sh`` script.
 
 The script usage is::
 
    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.
+For both scripts, the -n option specifies a number of commits from HEAD,
+and the -r option specifies a ``git log`` range.
 
-Additionally, when contributing to the DTS tool, patches should also be checked using
+Additionally, when contributing to the DTS tool, check patches using
 the ``dts-check-format.sh`` script in the ``devtools`` directory of the DPDK repo.
-To run the script, extra :ref:`Python dependencies <dts_deps>` are needed.
+Running the script requires extra :ref:`Python dependencies <dts_deps>`.
 
 .. _contrib_check_compilation:
 
 Checking Compilation
 --------------------
 
-Compilation of patches is to be tested with ``devtools/test-meson-builds.sh`` script.
+Test compilation of patches with the ``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
+By default, each build goes in a subfolder of the current working directory.
+However, to place the builds in a different location,
+set the environment variable ``DPDK_BUILD_TEST_DIR`` to that desired location.
+For example, setting ``DPDK_BUILD_TEST_DIR=__builds`` puts 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.
+Setting ``DPDK_BUILD_TEST_DIR`` to an absolute directory path (e.g., ``/tmp``) is also supported.
 
 
 .. _integrated_abi_check:
@@ -527,15 +538,15 @@ Checking ABI compatibility
 
 By default, ABI compatibility checks are disabled.
 
-To enable them, a reference version must be selected via the environment
+To enable them, select a reference version 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 ``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
+The ``devtools/test-meson-builds.sh`` script then builds this reference version
+in a temporary directory and stores 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.
+Set the environment variable ``DPDK_ABI_REF_DIR`` to place the results in
+a different location.
 
 Sample::
 
@@ -545,8 +556,8 @@ Sample::
 Sending Patches
 ---------------
 
-Patches should be sent to the mailing list using ``git send-email``.
-You can configure an external SMTP with something like the following::
+Send patches to the mailing list using ``git send-email``.
+Configure an external SMTP with something like the following::
 
    [sendemail]
        smtpuser = name@domain.com
@@ -556,27 +567,31 @@ You can configure an external SMTP with something like the following::
 
 See the `Git send-email <https://git-scm.com/docs/git-send-email>`_ documentation for more details.
 
-The patches should be sent to ``dev@dpdk.org``.
-If the patches are a change to existing files then you should send them TO the maintainer(s) and CC ``dev@dpdk.org``.
-The appropriate maintainer can be found in the ``MAINTAINERS`` file::
+Send patches to ``dev@dpdk.org``.
+If the patches change existing files, send them TO the maintainer(s) and CC ``dev@dpdk.org``.
+Find the appropriate maintainer 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::
+The script ``get-maintainer.sh`` can select maintainers automatically::
 
   git send-email --to-cmd ./devtools/get-maintainer.sh --cc dev@dpdk.org 000*.patch
 
-You can test the emails by sending it to yourself or with the ``--dry-run`` option.
+Send new additions without a maintainer::
+
+   git send-email --to dev@dpdk.org 000*.patch
+
+Test the emails by sending them to yourself or with the ``--dry-run`` option.
 
-If the patch is in relation to a previous email thread you can add it to the same thread using the Message ID::
+If the patch relates to a previous email thread, add it to the same thread using the Message ID::
 
    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,
+Find the Message ID in the raw text of emails or at the top of each Patchwork patch,
 `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.
+Once submitted, your patches appear on the mailing list and in Patchwork.
 
 Experienced committers may send patches directly with ``git send-email`` without the ``git format-patch`` step.
 The options ``--annotate`` and ``confirm = always`` are recommended for checking patches before sending.
@@ -587,11 +602,11 @@ 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``,
+In this case, send the patch(es) 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
+Given that multiple stable releases are maintained simultaneously,
+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.
 
@@ -599,7 +614,7 @@ and also optionally in the cover letter or in the annotation.
 The Review Process
 ------------------
 
-Patches are reviewed by the community, relying on the experience and
+The community reviews patches, relying on the experience and
 collaboration of the members to double-check each other's work. There are a
 number of ways to indicate that you have checked a patch on the mailing list.
 
@@ -607,8 +622,8 @@ number of ways to indicate that you have checked a patch on the mailing list.
 Tested, Acked and Reviewed by
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To indicate that you have interacted with a patch on the mailing list you
-should respond to the patch in an email with one of the following tags:
+To indicate that you have interacted with a patch on the mailing list,
+respond to the patch in an email with one of the following tags:
 
  * Reviewed-by:
  * Acked-by:
@@ -626,36 +641,35 @@ tag is given here for reference:
 
 .. _statement: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight
 
-``Reviewed-by:`` is a strong statement_ that the patch is an appropriate state
+``Reviewed-by:`` is a strong statement_ that the patch is in an appropriate state
 for merging without any remaining serious technical issues. Reviews from
-community members who are known to understand the subject area and to perform
-thorough reviews will increase the likelihood of the patch getting merged.
+community members who understand the subject area and perform
+thorough reviews increase the likelihood of the patch getting merged.
 
-``Acked-by:`` is a record that the person named was not directly involved in
-the preparation of the patch but wishes to signify and record their acceptance
+``Acked-by:`` records that the person named was not directly involved in
+preparing the patch but wishes to signify and record their acceptance
 and approval of it.
 
-``Tested-by:`` indicates that the patch has been successfully tested (in some
-environment) by the person named.
+``Tested-by:`` indicates that the person named has successfully tested the patch
+(in some environment).
 
-``Reported-by:`` is used to acknowledge person who found or reported the bug.
+``Reported-by:`` acknowledges the person who found or reported the bug.
 
-``Suggested-by:`` indicates that the patch idea was suggested by the named
-person.
+``Suggested-by:`` indicates that the named person suggested the patch idea.
 
 
 Frequency and volume of patches
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Please allow at least 24 hours to pass between posting patch revisions.
+Allow at least 24 hours between posting patch revisions.
 This ensures reviewers from different geographical regions have time to provide feedback.
-Additionally, please do not wait too long (read: weeks) between revisions
+Additionally, do not wait too long (i.e., weeks) between revisions
 as this makes it harder for reviewers and maintainers
 to recall the context of the previous posting.
 If you have not received any feedback within a week,
 it is appropriate to send a ping to the mailing list.
 
-Please do not post new revisions without addressing all feedback.
+Do not post new revisions without addressing all feedback.
 Make sure that all outstanding items have been addressed
 before posting a new revision for review
 (this should involve replying to all the feedback).
@@ -671,18 +685,18 @@ Your changes are expected to pass on an x86/x86-64 Linux system.
 The infrastructure running the tests is a shared resource among all developers on the project,
 and many frequent reposts will result in delays for all developers.
 We do our best to include CI and self-test infrastructure
-that can be used on an individual developer basis.
+that developers can use individually.
 
 For details on running the unit tests, see :doc:`unit_test`.
 It is also recommended to run the :doc:`DTS <../tools/dts>` comprehensive tests.
 Finally, you can also push to a branch on the GitHub service
 to trigger a comprehensive set of compile and unit test runs.
 
-Please keep all patch sets to a reasonable length.
-Too many or too large patches and series can quickly become very difficult
-for a reasonable review.
-It is recommended to appropriately split patches and series
-to groups of digestible logical changes.
+Keep all patch sets to a reasonable length.
+Too many or too large patches and series can quickly become difficult
+to review reasonably.
+Appropriately split patches and series
+into groups of digestible logical changes.
 
 
 Steps to getting your patch merged
@@ -695,39 +709,39 @@ patch accepted. The general cycle for patch review and acceptance is:
 
 #. Check the automatic test reports in the coming hours.
 
-#. Wait for review comments. While you are waiting review some other patches.
+#. Wait for review comments. While you are waiting, review some other patches.
 
-#. Fix the review comments and submit a ``v n+1`` patchset::
+#. Fix the review comments and submit a ``v n+1`` patch set::
 
       git format-patch -3 -v 2
 
 #. Update Patchwork to mark your previous patches as "Superseded".
 
-#. If the patch is deemed suitable for merging by the relevant maintainer(s) or other developers they will ``ack``
+#. If the relevant maintainer(s) or other developers deem the patch suitable for merging, they will ``ack``
    the patch with an email that includes something like::
 
       Acked-by: Alex Smith <alex.smith@example.com>
 
-   **Note**: When acking patches please remove as much of the text of the patch email as possible.
+   **Note**: When acking patches, remove as much of the text of the patch email as possible.
    It is generally best to delete everything after the ``Signed-off-by:`` line.
 
 #. Having the patch ``Reviewed-by:`` and/or ``Tested-by:`` will also help the patch to be accepted.
 
-#. If the patch isn't deemed suitable based on being out of scope or conflicting with existing functionality
+#. If the patch is deemed unsuitable based on being out of scope or conflicting with existing functionality,
    it may receive a ``nack``.
    In this case you will need to make a more convincing technical argument in favor of your patches.
 
-#. In addition a patch will not be accepted if it doesn't address comments from a previous version with fixes or
+#. In addition, a patch will not be accepted if it does not address comments from a previous version with fixes or
    valid arguments.
 
-#. It is the responsibility of a maintainer to ensure that patches are reviewed and to provide an ``ack`` or
+#. Maintainers are responsible for ensuring that patches are reviewed and for providing an ``ack`` or
    ``nack`` of those patches as appropriate.
 
-#. Once a patch has been acked by the relevant maintainer, reviewers may still comment on it for a further
+#. Once the relevant maintainer has acked a patch, reviewers may still comment on it for a further
    two weeks. After that time, the patch should be merged into the relevant git tree for the next release.
    Additional notes and restrictions:
 
-   * Patches should be acked by a maintainer at least two days before the release merge
+   * Maintainers should ack patches at least two days before the release merge
      deadline, in order to make that release.
    * For patches acked with less than two weeks to go to the merge deadline, all additional
      comments should be made no later than two days before the merge deadline.
@@ -742,11 +756,11 @@ patch accepted. The general cycle for patch review and acceptance is:
 Milestones definition
 ---------------------
 
-Each DPDK release has milestones that help everyone to converge to the release date.
+Each DPDK release has milestones that help everyone converge to the release date.
 The following is a list of these milestones together with
 concrete definitions and expectations for a typical release cycle.
-An average cycle lasts 3 months and have 4 release candidates in the last month.
-Test reports are expected to be received after each release candidate.
+An average cycle lasts 3 months and has 4 release candidates in the last month.
+Test reports are expected after each release candidate.
 The number and expectations of release candidates might vary slightly.
 The schedule is updated in the `roadmap <https://core.dpdk.org/roadmap/#dates>`_.
 
@@ -759,14 +773,14 @@ Roadmap
 ~~~~~~~
 
 * Announce new features in libraries, drivers, applications, and examples.
-* To be published before the previous release.
+* Publish before the previous release.
 
 Proposal Deadline
 ~~~~~~~~~~~~~~~~~
 
-* Must send an RFC (Request For Comments) or a complete patch of new features.
+* Send an RFC (Request For Comments) or a complete patch of new features.
 * Early RFC gives time for design review before complete implementation.
-* Should include at least the API changes in libraries and applications.
+* Include at least the API changes in libraries and applications.
 * Library code should be quite complete at the deadline.
 * Nice to have: driver implementation, example code, and documentation.
 
@@ -774,15 +788,15 @@ rc1
 ~~~
 
 * Priority: libraries. No library feature should be accepted after -rc1.
-* API changes or additions must be implemented in libraries.
+* Implement API changes or additions in libraries.
 * The API must include Doxygen documentation
   and be part of the relevant .rst files (library-specific and release notes).
-* API should be used in a test application (``/app``).
+* Use the API in a test application (``/app``).
 * At least one PMD should implement the API.
   It may be a draft sent in a separate series.
-* The above should be sent to the mailing list at least 2 weeks before -rc1
-  to give time for review and maintainers approval.
-* If no review after 10 days, a reminder should be sent.
+* Send the above to the mailing list at least 2 weeks before -rc1
+  to give time for review and maintainer approval.
+* If no review after 10 days, send a reminder.
 * Nice to have: example code (``/examples``)
 
 rc2
@@ -791,17 +805,17 @@ rc2
 * Priority: drivers. No driver feature should be accepted after -rc2.
 * A driver change must include documentation
   in the relevant .rst files (driver-specific and release notes).
-* Driver changes should be sent to the mailing list before -rc1 is released.
+* Send driver changes to the mailing list before -rc1 is released.
 
 rc3
 ~~~
 
 * Priority: applications. No application feature should be accepted after -rc3.
-* New functionality that does not depend on libraries update
+* New functionality that does not depend on library updates
   can be integrated as part of -rc3.
 * The application change must include documentation in the relevant .rst files
   (application-specific and release notes if significant).
-* Libraries and drivers cleanup are allowed.
+* Library and driver cleanup is allowed.
 * Small driver reworks.
 
 rc4
@@ -811,4 +825,4 @@ rc4
 * Critical bug fixes only.
 
 .. note::
-   Bug fixes are integrated as early as possible at any stage.
+   Integrate bug fixes as early as possible at any stage.
-- 
2.51.0

[PATCH v2 09/12] doc: improve stable releases documentation

[Stephen Hemminger]

Rewrite the stable releases and LTS documentation for clarity
- Converting passive voice to active voice
- Restructuring content with bullet points for scannability
- Simplifying verbose explanations
- Removing redundant phrasing
- Making backport criteria more concise

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/stable.rst | 147 ++++++++++++-----------------
 1 file changed, 60 insertions(+), 87 deletions(-)

diff --git a/doc/guides/contributing/stable.rst b/doc/guides/contributing/stable.rst
index 808e7fa779..6065163e75 100644
--- a/doc/guides/contributing/stable.rst
+++ b/doc/guides/contributing/stable.rst
@@ -6,84 +6,69 @@
 DPDK Stable Releases and Long Term Support
 ==========================================
 
-This section sets out the guidelines for the DPDK Stable Releases and the DPDK
-Long Term Support releases (LTS).
-
+This section outlines the guidelines for DPDK Stable Releases and Long Term Support (LTS) releases.
 
 Introduction
 ------------
 
-The purpose of the DPDK Stable Releases is to maintain releases of DPDK with
-backported fixes over an extended period of time. This provides downstream
-consumers of DPDK with a stable target on which to base applications or
-packages.
-
-The primary characteristics of stable releases is that they attempt to
-fix issues and not introduce any new regressions while keeping backwards
-compatibility with the initial release of the stable version.
+The purpose of DPDK Stable Releases is to maintain DPDK versions with backported
+fixes over an extended period. This allows downstream users to base applications
+or packages on a stable, well-maintained version of DPDK.
 
-The Long Term Support release (LTS) is a designation applied to a Stable
-Release to indicate longer term support.
+The primary goal of stable releases is to fix issues without introducing regressions,
+while preserving backward compatibility with the original version.
 
+LTS (Long Term Support) is a designation given to specific stable releases to indicate
+extended support duration.
 
 Stable Releases
 ---------------
 
-Any release of DPDK can be designated as a Stable Release if a
-maintainer volunteers to maintain it and there is a commitment from major
-contributors to validate it before releases.
-If a version is to be a "Stable Release", it should be designated as such
-within one month of that version being initially released.
+Any DPDK release may become a Stable Release if a maintainer volunteers to support it
+and major contributors commit to validating it before each release.
+This designation should be made within one month of the version's initial release.
 
-A Stable Release is used to backport fixes from an ``N`` release back to an
+Stable Releases are typically used to backport fixes from an ``N`` release to an
 ``N-1`` release, for example, from 16.11 to 16.07.
 
-The duration of a stable is one complete release cycle (4 months). It can be
-longer, up to 1 year, if a maintainer continues to support the stable branch,
-or if users supply backported fixes, however the explicit commitment should be
-for one release cycle.
-
-The release cadence is determined by the maintainer based on the number of
-bugfixes and the criticality of the bugs. Releases should be coordinated with
-the validation engineers to ensure that a tagged release has been tested.
-
-
-LTS Release
------------
+* The standard support duration is one full release cycle (4 months).
+* This may extend up to one year if the maintainer continues support or if users provide backported fixes.
+* The maintainer determines the release cadence based on the volume and criticality of fixes.
+* Coordinate releases with validation engineers to ensure proper testing before tagging.
 
-A stable release can be designated as an LTS release based on community
-agreement and a commitment from a maintainer. The current policy is that each
-year's November (X.11) release will be maintained as an LTS for 3 years,
-however that is dependent on continued community support for validation.
+LTS Releases
+------------
 
-After the X.11 release, an LTS branch will be created for it at
-https://git.dpdk.org/dpdk-stable where bugfixes will be backported to.
+A Stable Release can be promoted to an LTS release through community agreement
+and a maintainer's commitment.
 
-A LTS release may align with the declaration of a new major ABI version,
-please read the :doc:`abi_policy` for more information.
+* The current policy designates each November release (X.11) as an LTS and maintains it for 3 years,
+  contingent on community validation support.
+* After release, an LTS branch is created at https://git.dpdk.org/dpdk-stable
+  where bugfixes are backported.
+* An LTS release may align with the declaration of a new major ABI version.
+  See the :doc:`abi_policy` for more information.
 
-It is anticipated that there will be at least 3 releases per year of the LTS
-or approximately 1 every 4 months. This is done to align with the DPDK main
-branch releases so that fixes have already gone through validation as part of
-the DPDK main branch release validation. However, the cadence can be shorter or
-longer depending on the number and criticality of the backported
-fixes. Releases should be coordinated with the validation engineers to ensure
-that a tagged release has been tested.
+Release Cadence:
 
-For a list of the currently maintained stable/LTS branches please see
-the latest `stable roadmap <https://core.dpdk.org/roadmap/#stable>`_.
+* At least three LTS updates per year (roughly one every four months).
+* Aligned with main DPDK releases to leverage shared validation.
+* Frequency may vary depending on the urgency and volume of fixes.
+* Coordinate validation with test engineers.
 
-At the end of the 3 years, a final X.11.N release will be made and at that
-point the LTS branch will no longer be maintained with no further releases.
+For a list of the currently maintained stable/LTS branches, see
+the `stable roadmap <https://core.dpdk.org/roadmap/#stable>`_.
 
+At the end of the 3-year period, a final X.11.N release is made,
+after which the LTS branch is no longer maintained.
 
-What changes should be backported
+What Changes Should Be Backported
 ---------------------------------
 
-Backporting should be limited to bug fixes. All patches accepted on the main
-branch with a Fixes: tag should be backported to the relevant stable/LTS
-branches, unless the submitter indicates otherwise. If there are exceptions,
-they will be discussed on the mailing lists.
+Limit backports to bug fixes.
+
+All patches accepted on the main branch with a ``Fixes:`` tag should be backported
+to the relevant stable/LTS branches, unless the submitter indicates otherwise.
 
 Fixes suitable for backport should have a ``Cc: stable@dpdk.org`` tag in the
 commit message body as follows::
@@ -97,49 +82,37 @@ commit message body as follows::
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
 
-
 Fixes not suitable for backport should not include the ``Cc: stable@dpdk.org`` tag.
 
-To support the goal of stability and not introducing regressions,
-new code being introduced is limited to bug fixes.
 New features should not be backported to stable releases.
-
-In some limited cases, it may be acceptable to backport a new feature
-to a stable release. Some of the factors which impact the decision by
-stable maintainers are as follows:
-
-* Does the feature break API/ABI?
-* Does the feature break backwards compatibility?
-* Is it for the latest LTS release (to avoid LTS upgrade issues)?
-* Is there a commitment from the proposer or affiliation to validate the feature
-  and check for regressions in related functionality?
-* Is there a track record of the proposer or affiliation validating stable releases?
-* Is it obvious that the feature will not impact existing functionality?
-* How intrusive is the code change?
-* What is the scope of the code change?
-* Does it impact common components or vendor specific?
-* Is there a justifiable use case (a clear user need)?
-* Is there a community consensus about the backport?
-
-Performance improvements are generally not considered to be fixes,
-but may be considered in some cases where:
+In limited cases, a new feature may be acceptable if:
+
+* It does not break API or ABI.
+* It preserves backward compatibility.
+* It targets the latest LTS release (to help with upgrade paths).
+* The proposer commits to testing the feature and monitoring regressions.
+* The proposer or their organization has a track record of validating stable releases.
+* It clearly does not impact existing functionality.
+* The change is minimally invasive and scoped.
+* It affects vendor-specific components rather than common ones.
+* There is a justifiable use case (a clear user need).
+* There is community consensus about the backport.
+
+Performance improvements are generally not considered fixes,
+but may be considered in cases where:
 
 * It is fixing a performance regression that occurred previously.
 * An existing feature in LTS is not usable as intended without it.
 
 APIs marked as ``experimental`` are not considered part of the ABI version
-and can be changed without prior notice. This is necessary for the API to be
-improved and stabilized and become part of the ABI version in the future.
-
-However, in LTS releases ``experimental`` API should not be changed as there
-will not be a future ABI version on the branch and compatibility with previous
-release of an LTS version is of the highest importance.
+and can be changed without prior notice in mainline development.
+However, in LTS releases, ``experimental`` APIs should not be changed,
+as compatibility with previous releases of an LTS version is paramount.
 
 The Stable Mailing List
 -----------------------
 
-The Stable and LTS release are coordinated on the stable@dpdk.org mailing
-list.
+Stable and LTS releases are coordinated on the stable@dpdk.org mailing list.
 
 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>`_
@@ -149,7 +122,7 @@ mailing list.
 Releasing
 ---------
 
-A Stable Release will be released by:
+A Stable Release is made by:
 
 * Tagging the release with YY.MM.n (year, month, number).
 * Uploading a tarball of the release to dpdk.org.
-- 
2.51.0

[PATCH v2 10/12] doc: improve vulnerability process documentation

[Stephen Hemminger]

Improve the vulnerability management documentation
- Converting passive voice to active voice
- Using clearer section headings
- Simplifying verbose explanations
- Making reporting instructions more direct
- Fixing broken RST link syntax for mailing lists

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/vulnerability.rst | 140 ++++++++++------------
 1 file changed, 65 insertions(+), 75 deletions(-)

diff --git a/doc/guides/contributing/vulnerability.rst b/doc/guides/contributing/vulnerability.rst
index fc60e02e37..1d616d203a 100644
--- a/doc/guides/contributing/vulnerability.rst
+++ b/doc/guides/contributing/vulnerability.rst
@@ -7,10 +7,9 @@ DPDK Vulnerability Management Process
 Scope
 -----
 
-Only the main repositories (dpdk and dpdk-stable) of the core project
-are in the scope of this security process (including experimental APIs).
-If a stable branch is declared unmaintained (end of life),
-no fix will be applied.
+This security process covers only the main repositories (dpdk and dpdk-stable)
+of the core project (including experimental APIs).
+The team will not apply fixes to stable branches declared unmaintained (end of life).
 
 All vulnerabilities are bugs, but not every bug is a vulnerability.
 Vulnerabilities compromise one or more of:
@@ -19,79 +18,71 @@ Vulnerabilities compromise one or more of:
 * Integrity (trustworthiness and correctness).
 * Availability (uptime and service).
 
-If in doubt, please consider the vulnerability as security sensitive.
+If in doubt, consider the vulnerability as security sensitive.
 At worst, the response will be to report the bug through the usual channels.
 
 
-Finding
--------
+Finding Security Issues
+-----------------------
 
 There is no pro-active security engineering effort at the moment.
 
-Please report any security issue you find in DPDK as described below.
+Report any security issue you find in DPDK as described below.
 
 
-Report
-------
+Reporting Security Issues
+-------------------------
 
-Do not use Bugzilla (unsecured).
-Instead, send GPG-encrypted emails
-to `security@dpdk.org <https://core.dpdk.org/security#contact>`_.
-Anyone can post to this list.
-In order to reduce the disclosure of a vulnerability in the early stages,
-membership of this list is intentionally limited to a `small number of people
-<https://mails.dpdk.org/roster/security>`_.
+Do not use Bugzilla to report security vulnerabilities, as it is not secured for such communication.
+Instead, send a GPG-encrypted email to `security@dpdk.org <https://core.dpdk.org/security#contact>`_.
+This address is open to all, but access to its inbox is intentionally limited to a small group
+to minimize the risk of early disclosure.
 
-It is additionally encouraged to GPG-sign one-on-one conversations
-as part of the security process.
+GPG-sign any one-on-one correspondence related to the vulnerability
+report as part of maintaining a secure communication process.
 
-As it is with any bug, the more information provided,
-the easier it will be to diagnose and fix.
-If you already have a fix, please include it with your report,
-as that can speed up the process considerably.
+As with any bug report, detailed information greatly aids in diagnosing and resolving the issue.
+If you have already developed a fix, include it in your submission to help accelerate resolution.
 
-In the report, please note how you would like to be credited
-for discovering the issue
-and the details of any embargo you would like to impose.
+In your report, specify how you would like to be credited for the discovery and mention any embargo
+period you wish to impose.
 
-If the vulnerability is not public yet,
-no patch or information should be disclosed publicly.
-If a fix is already published,
-the reporting process must be followed anyway, as described below.
+If the vulnerability has not yet been made public, do not disclose patches or related information
+publicly. Even if a fix has already been published, you must still follow the proper reporting process outlined here.
 
 
 Confirmation
 ------------
 
-Upon reception of the report, a security team member should reply
-to the reporter acknowledging that the report has been received.
+Upon receiving the report, a security team member should reply
+to the reporter acknowledging receipt.
 
 The DPDK security team reviews the security vulnerability reported.
-Area experts not members of the security team may be involved in the process.
-In case the reported issue is not qualified as a security vulnerability,
+Area experts who are not members of the security team may be involved in the process.
+If the reported issue does not qualify as a security vulnerability,
 the security team will request the submitter to report it
 using the usual channel (Bugzilla).
-If qualified, the security team will assess which DPDK version are affected.
-A bugzilla ID (allocated in a `reserved pool
+If qualified, the security team assesses which DPDK versions are affected.
+A bugzilla ID (allocated from a `reserved pool
 <https://bugs.dpdk.org/buglist.cgi?f1=bug_group&o1=equals&v1=security>`_)
 is assigned to the vulnerability, and kept empty until public disclosure.
 
-The security team calculates the severity score with
+The security team calculates the severity score with the
 `CVSS calculator <https://www.first.org/cvss/calculator/3.0>`_
 based on inputs from the reporter and its own assessment of the vulnerability,
 and agrees on the score with the reporter.
 
 An embargo may be put in place depending on the severity of the vulnerability.
-If an embargo is decided, its duration should be suggested by the security team
-and negotiated with the reporter.
+If an embargo is decided, the security team should suggest the duration
+and negotiate with the reporter.
 Embargo duration between vulnerability confirmation and public disclosure
 should be between **one and ten weeks**.
 If an embargo is not required, the vulnerability may be fixed
 using the standard patch process, once a CVE number has been assigned.
 
-The confirmation mail should be sent within **3 business days**.
+Send the confirmation mail within **3 business days**.
 
-Following information must be included in the mail:
+Include the following information in the mail:
 
 * Confirmation
 * CVSS severity and score
@@ -110,7 +101,7 @@ from the reporter before finalizing the document.
 When the document is final, the security team needs to
 request a CVE identifier from a CNA.
 
-The CVE request should be sent
+Send the CVE request
 to `secalert@redhat.com <mailto:secalert@redhat.com>`_
 using GPG encrypted email
 (see `contact details <https://access.redhat.com/security/team/contact>`_).
@@ -161,19 +152,18 @@ CVE Request Template without Embargo
 Fix Development and Review
 --------------------------
 
-If the fix is already published, this step is skipped,
-and the pre-release disclosure is replaced with the private disclosure,
-as described below. It must not be considered as the standard process.
+If the fix is already published, skip this step,
+and replace the pre-release disclosure with the private disclosure,
+as described below. This should not be considered the standard process.
 
-This step may be started in parallel with CVE creation.
-The patches fixing the vulnerability are developed and reviewed
-by the security team and
-by elected area experts that agree to maintain confidentiality.
+This step may start in parallel with CVE creation.
+The security team and elected area experts who agree to maintain confidentiality
+develop and review patches fixing the vulnerability.
 
-The CVE id and the bug id must be referenced in the patch if there is no
-embargo, or if there is an embargo, but it will be lifted when the release
-including the patch is published. If the embargo is going to be lifted after the
-release, then the CVE and bug ids must be omitted from the commit message.
+Reference the CVE id and the bug id in the patch if there is no
+embargo, or if the embargo will be lifted when the release
+including the patch is published. If the embargo will be lifted after the
+release, omit the CVE and bug ids from the commit message.
 
 Backports to the identified affected versions are done once the fix is ready.
 
@@ -181,32 +171,32 @@ Backports to the identified affected versions are done once the fix is ready.
 Pre-Release Disclosure
 ----------------------
 
-When the fix is ready, the security advisory and patches are sent
+When the fix is ready, send the security advisory and patches
 to downstream stakeholders
 (`security-prerelease@dpdk.org <mailto:security-prerelease@dpdk.org>`_),
 specifying the date and time of the end of the embargo.
-The communicated public disclosure date should be **less than one week**
+The communicated public disclosure date should be **less than one week**.
 
 Downstream stakeholders are expected not to deploy or disclose patches
-until the embargo is passed, otherwise they will be removed from the list.
+until the embargo passes; otherwise they will be removed from the list.
 
 Downstream stakeholders (in `security-prerelease list
-<https://mails.dpdk.org/roster/security-prerelease>`_), are:
+<https://mails.dpdk.org/roster/security-prerelease>`_) are:
 
 * Operating system vendors known to package DPDK
 * Major DPDK users, considered trustworthy by the technical board, who
   have made the request to `techboard@dpdk.org <mailto:techboard@dpdk.org>`_
 
-The `OSS security private mailing list mailto:distros@vs.openwall.org>` will
+The `OSS security private mailing list <mailto:distros@vs.openwall.org>`_ will
 also be contacted one week before the end of the embargo, as indicated by `the
-OSS-security process <https://oss-security.openwall.org/wiki/mailing-lists/distros>`
+OSS-security process <https://oss-security.openwall.org/wiki/mailing-lists/distros>`_
 and using the PGP key listed on the same page, describing the details of the
 vulnerability and sharing the patch[es]. Distributions and major vendors follow
 this private mailing list, and it functions as a single point of contact for
 embargoed advance notices for open source projects.
 
-The security advisory will be based on below template,
-and will be sent signed with a security team's member GPG key.
+The security advisory will be based on the template below,
+and will be sent signed with a security team member's GPG key.
 
 
 Pre-Release Mail Template
@@ -234,7 +224,7 @@ Pre-Release Mail Template
   Please do not make the issue public (or release public patches)
   before this coordinated embargo date.
 
-If the issue is leaked during the embargo, the same procedure is followed
+If the issue is leaked during the embargo, follow the same procedure
 with only a few days delay between the pre-release and the public disclosure.
 
 
@@ -242,9 +232,9 @@ Private Disclosure
 ------------------
 
 If a vulnerability is unintentionally already fixed in the public repository,
-a security advisory is sent to downstream stakeholders
+send a security advisory to downstream stakeholders
 (`security-prerelease@dpdk.org <mailto:security-prerelease@dpdk.org>`_),
-giving few days to prepare for updating before the public disclosure.
+giving a few days to prepare for updating before the public disclosure.
 
 
 Private Disclosure Mail Template
@@ -275,23 +265,23 @@ Private Disclosure Mail Template
 Public Disclosure
 -----------------
 
-On embargo expiration, following tasks will be done simultaneously:
+When the embargo expires, carry out the following actions simultaneously:
 
-* The assigned bug is filled by a member of the security team,
-  with all relevant information, and it is made public.
-* The patches are pushed to the appropriate branches.
-* For long and short term stable branches fixed,
-  new versions should be released.
+* A security team member files the assigned bug with all relevant details and makes it publicly accessible.
 
-Releases on Monday to Wednesday are preferred, so that system administrators
-do not have to deal with security updates over the weekend.
+* Push the associated patches to the appropriate branches.
 
-The security advisory is posted
+* Release updated versions for all affected stable branches, both short-term and long-term.
+
+To ease adoption by system administrators, preferably schedule security releases
+between Monday and Wednesday, avoiding weekends.
+
+Post the security advisory
 to `announce@dpdk.org <mailto:announce@dpdk.org>`_ and to `the public OSS-security
-mailing list <mailto:oss-security@lists.openwall.com>` as soon as the patches
+mailing list <mailto:oss-security@lists.openwall.com>`_ as soon as the patches
 are pushed to the appropriate branches.
 
-Patches are then sent to `dev@dpdk.org <mailto:dev@dpdk.org>`_
+Send patches to `dev@dpdk.org <mailto:dev@dpdk.org>`_
 and `stable@dpdk.org <mailto:stable@dpdk.org>`_ accordingly.
 
 
-- 
2.51.0

[PATCH v2 11/12] doc: improve unit test guide readability

[Stephen Hemminger]

Improve the unit test documentation
- Converting passive voice to active voice
- Using imperative mood for instructions
- Simplifying wordy constructions
- Removing unnecessary include statements from code example
- Fixing minor grammar and punctuation issues
- Add missing subject in sentence about DPDK_TEST_PARAMS
- Add missing article "a" before "test case"
- Fix missing closing backtick in meson test example
- Use consistent double backticks for dpdk-test command references
- Use double backticks for file path reference
- Correct "test case" to "test suite" in DPDK_TEST example description
- Clarify "cryptodev" reference to "crypto devices"
- Remove unnecessary quotes around return code values

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/unit_test.rst | 129 ++++++++++++--------------
 1 file changed, 60 insertions(+), 69 deletions(-)

diff --git a/doc/guides/contributing/unit_test.rst b/doc/guides/contributing/unit_test.rst
index 0c76921299..a92953eab1 100644
--- a/doc/guides/contributing/unit_test.rst
+++ b/doc/guides/contributing/unit_test.rst
@@ -9,7 +9,7 @@ tests to the in-tree DPDK test suites.
 
 The DPDK test suite model is loosely based on the xUnit model,
 where tests are grouped into test suites, and suites are run by runners.
-For a basic overview, see the basic Wikipedia article on `xUnit
+For a basic overview, see the Wikipedia article on `xUnit
 <https://en.wikipedia.org/wiki/XUnit>`_.
 
 
@@ -18,32 +18,32 @@ Background
 
 The in-tree testing infrastructure for DPDK consists of
 multiple applications and support tools.
-The primary tools are the `dpdk-test` application,
+The primary tools are the ``dpdk-test`` application
 and the ``meson test`` infrastructure.
-These two are the primary ways through which
-a user will interact with the DPDK testing infrastructure.
+These two are the primary ways
+users interact with the DPDK testing infrastructure.
 
-There exists a bit of confusion with the test suite and test case separation
-with respect to `dpdk-test` and ``meson test``.
+Some confusion exists regarding test suite and test case separation
+between ``dpdk-test`` and ``meson test``.
 Both have a concept of test suite and test case.
 In both, the concept is similar.
 A test suite is a group of test cases,
 and a test case represents the steps needed to test a particular set of code.
-Where needed, they will be disambiguated by the word `Meson`
+Where needed, they will be disambiguated by the word Meson
 to denote a Meson test suite / case.
 
 
 Running a test
 --------------
 
-DPDK tests are run via the main test runner, the `dpdk-test` app.
-The `dpdk-test` app is a command-line interface that facilitates
+DPDK tests run via the main test runner, the ``dpdk-test`` app.
+The ``dpdk-test`` app is a command-line interface that facilitates
 running various tests or test suites.
 
 There are three modes of operation.
-The first mode is as an interactive command shell
+The first mode is an interactive command shell
 that allows launching specific test suites.
-This is the default operating mode of `dpdk-test` and can be done by::
+This is the default operating mode of ``dpdk-test`` and can be invoked by::
 
    $ ./build/app/test/dpdk-test --dpdk-options-here
    EAL: Detected 4 lcore(s)
@@ -58,14 +58,14 @@ This is the default operating mode of `dpdk-test` and can be done by::
    APP: HPET is not enabled, using TSC as default timer
    RTE>>
 
-At the prompt, simply type the name of the test suite you wish to run
+At the prompt, type the name of the test suite you wish to run
 and it will execute.
 
-The second form is useful for a scripting environment,
+The second form is useful for a scripting environment
 and is used by the DPDK Meson build system.
-This mode is invoked by
+Invoke this mode by
 assigning a specific test suite name to the environment variable ``DPDK_TEST``
-before invoking the `dpdk-test` command, such as::
+before invoking the ``dpdk-test`` command, such as::
 
    $ DPDK_TEST=version_autotest ./build/app/test/dpdk-test --dpdk-options-here
    EAL: Detected 4 lcore(s)
@@ -83,9 +83,9 @@ before invoking the `dpdk-test` command, such as::
    Test OK
    RTE>>$
 
-The above shows running a specific test case.
-On success, the return code will be '0',
-otherwise it will be set to some error value (such as '255', or a negative value).
+The above shows running a specific test suite.
+On success, the return code will be 0;
+otherwise it will be set to some error value (such as 255).
 
 The third form is an alternative
 to providing the test suite name in an environment variable.
@@ -110,20 +110,20 @@ The unit test app can accept test suite names via command line arguments::
 The primary benefit here is specifying multiple test names,
 which is not possible with the ``DPDK_TEST`` environment variable.
 
-Additionally, it is possible to specify additional test parameters
+Additionally, you can specify additional test parameters
 via the ``DPDK_TEST_PARAMS`` argument,
 in case some tests need additional configuration.
-This isn't currently used in the Meson test suites.
+This is not currently used in the Meson test suites.
 
 
 Running test cases via Meson
 ----------------------------
 
-In order to allow developers to quickly execute all the standard internal tests
+To allow developers to quickly execute all the standard internal tests
 without needing to remember or look up each test suite name,
 the build system includes a standard way of executing the Meson test suites.
 After building via ``ninja``, the ``meson test`` command
-with no arguments will execute the Meson test suites.
+with no arguments executes the Meson test suites.
 
 There are a number of pre-configured Meson test suites.
 The first is the **fast** test suite, which is the largest group of test cases.
@@ -131,11 +131,11 @@ These are the bulk of the unit tests to validate functional blocks.
 The second is the **perf** tests.
 These test suites can take longer to run and do performance evaluations.
 The third is the **driver** test suite,
-which is mostly for special hardware related testing (such as `cryptodev`).
+which is mostly for special hardware related testing (such as crypto devices).
 The fourth, and currently the last, suite is the **debug** suite.
-These tests mostly are used to dump system information.
+These tests mostly dump system information.
 
-The Meson test suites can be selected by adding the ``--suite`` option
+Select the Meson test suites by adding the ``--suite`` option
 to the ``meson test`` command.
 Ex: ``meson test --suite fast-tests``::
 
@@ -159,19 +159,19 @@ via the command line by adding the test names as an argument::
    1/1 DPDK:fast-tests / version_autotest OK             0.17s
    ...
 
-Note that these test cases must be known to Meson
+Note that Meson must know these test cases
 for the ``meson test`` command to run them.
-Simply adding a new test to the `dpdk-test` application isn't enough.
+Simply adding a new test to the ``dpdk-test`` application is not enough.
 See the section `Adding a suite or test case to Meson`_ for more details.
 
 
 Adding tests to dpdk-test application
 -------------------------------------
 
-Unit tests should be added to the system
-whenever we introduce new functionality to DPDK,
-as well as whenever a bug is resolved.
-This helps the DPDK project to catch regressions as they are introduced.
+Add unit tests to the system
+whenever introducing new functionality to DPDK
+or resolving a bug.
+This helps the DPDK project catch regressions as they occur.
 
 The DPDK test application supports two layers of tests:
    #. *test cases* which are individual tests
@@ -185,8 +185,8 @@ There are two important functions for interacting with the test harness:
    ``REGISTER_<MESON_SUITE>_TEST(command_name, function_to_execute)``
       Registers a test command with the name `command_name`
       and which runs the function `function_to_execute` when `command_name` is invoked.
-      The test is automatically added to the Meson test suite `<MESON_SUITE>` by this macro.
-      Examples would be ``REGISTER_DRIVER_TEST``, or ``REGISTER_PERF_TEST``.
+      This macro automatically adds the test to the Meson test suite `<MESON_SUITE>`.
+      Examples: ``REGISTER_DRIVER_TEST``, or ``REGISTER_PERF_TEST``.
       **NOTE:** The ``REGISTER_FAST_TEST`` macro is slightly different,
       in that it takes two additional parameters before the function name:
       the hugepage requirement (``NOHUGE_OK`` if the test can run without hugepages,
@@ -205,28 +205,19 @@ that runs at the beginning and end of the test suite execution.
 Each unit test has a similar function for test case setup and tear down.
 
 Each test suite may use a nested list of sub-testsuites,
-which are iterated by the ``unit_test_suite_runner``.
+which the ``unit_test_suite_runner`` iterates.
 This support allows for better granularity when designing test suites.
-The sub-testsuites list can also be used in parallel with the vector of test cases,
-in this case the test cases will be run,
-and then each sub-testsuite is executed.
+The sub-testsuites list can also be used in parallel with the vector of test cases;
+in this case, the test cases run first,
+then each sub-testsuite executes.
 To see an example of a test suite using sub-testsuites,
 see *app/test/test_cryptodev.c*.
 
-Test cases are added to the ``.unit_test_cases`` element
-of the appropriate unit test suite structure.
-An example of both a test suite and a case:
+Example of a test suite with a single test case:
 
 .. code-block:: c
    :linenos:
 
-   #include <time.h>
-
-   #include <rte_common.h>
-   #include <rte_cycles.h>
-   #include <rte_hexdump.h>
-   #include <rte_random.h>
-
    #include "test.h"
 
    static int testsuite_setup(void) { return TEST_SUCCESS; }
@@ -256,9 +247,9 @@ An example of both a test suite and a case:
    REGISTER_PERF_TEST(example_autotest, example_tests);
 
 The above code block is a small example
-that can be used to create a complete test suite with test case.
+that can be used to create a complete test suite with a test case.
 
-Sub-testsuites can be added to the ``.unit_test_suites`` element
+Add sub-testsuites to the ``.unit_test_suites`` element
 of the unit test suite structure, for example:
 
 .. code-block:: c
@@ -337,13 +328,13 @@ The first way to indicate a generic error is
 by returning a test result failure, using the ``TEST_FAILED`` error code.
 This is the most basic way of indicating that an error
 has occurred in a test routine.
-It isn't very informative to the user, so it should really be used in cases
+It is not very informative to the user, so use it in cases
 where the test has catastrophically failed.
 
 The preferred method of indicating an error is
 via the ``RTE_TEST_ASSERT`` family of macros,
-which will immediately return ``TEST_FAILED`` error condition,
-but will also log details about the failure.
+which immediately return ``TEST_FAILED`` error condition,
+but also log details about the failure.
 The basic form is:
 
 .. code-block:: c
@@ -352,20 +343,20 @@ The basic form is:
 
 In the above macro, *cond* is the condition to evaluate to **true**.
 Any generic condition can go here.
-The *msg* parameter will be a message to display if *cond* evaluates to **false**.
+The *msg* parameter is a message to display if *cond* evaluates to **false**.
 Some specialized macros already exist.
-See `lib/librte_eal/include/rte_test.h` for a list of defined test assertions.
+See ``lib/librte_eal/include/rte_test.h`` for a list of defined test assertions.
 
 Sometimes it is important to indicate that a test needs to be skipped,
-either because the environment isn't able to support running the test,
-or because some requisite functionality isn't available.
+either because the environment cannot support running the test,
+or because some requisite functionality is unavailable.
 The test suite supports returning a result of ``TEST_SKIPPED``
 during test case setup, or during test case execution
-to indicate that the preconditions of the test aren't available.
+to indicate that the preconditions of the test are not available.
 Example::
 
    $ meson test -C build --suite fast-tests
-   ninja: Entering directory `/home/aconole/git/dpdk/build
+   ninja: Entering directory `/home/aconole/git/dpdk/build'
    [2543/2543] Linking target app/test/dpdk-test.
    1/60 DPDK:fast-tests / acl_autotest          OK       3.17 s
    2/60 DPDK:fast-tests / bitops_autotest       OK       0.22 s
@@ -388,10 +379,10 @@ Example::
    $ meson test -C build --suite fast-tests
    $ ninja coverage-html -C build
 
-The above will generate an HTML report
-in the `build/meson-logs/coveragereport/` directory
+The above generates an HTML report
+in the ``build/meson-logs/coveragereport/`` directory
 that can be explored for detailed code covered information.
-This can be used to assist in test development.
+Use this to assist in test development.
 
 
 Adding a suite or test case to Meson
@@ -402,10 +393,10 @@ to register the test in dpdk-test, as described above.
 For example,
 defining the test command using ``REGISTER_PERF_TEST`` automatically
 adds the test to the perf-test meson suite.
-Once added, the new test will be run
+Once added, the new test runs
 as part of the appropriate class (fast, perf, driver, etc.).
 
-A user or developer can confirm that a test is known to Meson
+Confirm that a test is known to Meson
 by using the ``--list`` option::
 
    $ meson test -C build --list
@@ -413,12 +404,12 @@ by using the ``--list`` option::
    DPDK:fast-tests / bitops_autotest
    ...
 
-Some of these test suites are run during continuous integration tests,
+Some of these test suites run during continuous integration tests,
 making regression checking automatic for new patches submitted to the project.
 
 .. note::
 
-   The use of the old ``REGISTER_TEST_COMMAND`` macro
+   The old ``REGISTER_TEST_COMMAND`` macro
    to add a command without adding it to a meson test suite is deprecated.
    All new tests must be added to a test suite
    using the appropriate ``REGISTER_<SUITE>_TEST`` macro.
@@ -426,8 +417,8 @@ making regression checking automatic for new patches submitted to the project.
 Running cryptodev tests
 -----------------------
 
-When running cryptodev tests, the user must create any required virtual device
-via EAL arguments, as this is not automatically done by the test::
+When running cryptodev tests, create any required virtual device
+via EAL arguments, as this is not done automatically by the test::
 
    $ ./build/app/test/dpdk-test --vdev crypto_aesni_mb
    $ meson test -C build --suite driver-tests \
@@ -435,6 +426,6 @@ via EAL arguments, as this is not automatically done by the test::
 
 .. note::
 
-   The ``cryptodev_scheduler_autotest`` is the only exception to this.
-   This vdev will be created automatically by the test app,
+   The ``cryptodev_scheduler_autotest`` is the only exception.
+   This vdev is created automatically by the test app,
    as it requires a more complex setup than other vdevs.
-- 
2.51.0

[PATCH v2 12/12] doc: fix grammar and style in ABI versioning guide

[Stephen Hemminger]

Fix several issues in the ABI versioning documentation:

- Remove extra period after soname Wikipedia link
- Fix "it's" to "its" for possessive form
- Add missing "be" in "need to be carefully planned"
- Remove erroneous "is" in "it is may be required"
- Add missing "and" and "for" in ABI version support sentence
- Fix "Lets" to "Let's" contraction
- Remove stray semicolon in #include directive example
- Replace "comprised of" with "consists of"
- Fix missing period after "e.g" abbreviation
- Add missing apostrophe in "application's dependencies"
- Remove redundant "of the head" phrase
- Clarify "alias to experimental" wording

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/abi_versioning.rst | 32 +++++++++++-----------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst
index 2fa2b15edc..086f3d6016 100644
--- a/doc/guides/contributing/abi_versioning.rst
+++ b/doc/guides/contributing/abi_versioning.rst
@@ -17,19 +17,19 @@ System libraries usually adopt the familiar major and minor version naming
 convention, where major versions (e.g. ``librte_eal 21.x, 22.x``) are presumed
 to be ABI incompatible with each other and minor versions (e.g. ``librte_eal
 21.1, 21.2``) are presumed to be ABI compatible. A library's `soname
-<https://en.wikipedia.org/wiki/Soname>`_. is typically used to provide backward
+<https://en.wikipedia.org/wiki/Soname>`_ is typically used to provide backward
 compatibility information about a given library, describing the lowest common
 denominator ABI supported by the library. The soname or logical name for the
-library, is typically comprised of the library's name and major version e.g.
+library typically consists of the library's name and major version e.g.
 ``librte_eal.so.21``.
 
 During an application's build process, a library's soname is noted as a runtime
 dependency of the application. This information is then used by the `dynamic
 linker <https://en.wikipedia.org/wiki/Dynamic_linker>`_ when resolving the
-applications dependencies at runtime, to load a library supporting the correct
+application's dependencies at runtime, to load a library supporting the correct
 ABI version. The library loaded at runtime therefore, may be a minor revision
 supporting the same major ABI version (e.g. ``librte_eal.21.2``), as the library
-used to link the application (e.g ``librte_eal.21.0``).
+used to link the application (e.g. ``librte_eal.21.0``).
 
 .. _major_abi_versions:
 
@@ -37,7 +37,7 @@ Major ABI versions
 ------------------
 
 An ABI version change to a given library, especially in core libraries such as
-``librte_mbuf``, may cause an implicit ripple effect on the ABI of it's
+``librte_mbuf``, may cause an implicit ripple effect on the ABI of its
 consuming libraries, causing ABI breakages. There may however be no explicit
 reason to bump a dependent library's ABI version, as there may have been no
 obvious change to the dependent library's API, even though the library's ABI
@@ -47,11 +47,11 @@ This interdependence of DPDK libraries, means that ABI versioning of libraries
 is more manageable at a project level, with all project libraries sharing a
 **single ABI version**. In addition, the need to maintain a stable ABI for some
 number of releases as described in the section :doc:`abi_policy`, means
-that ABI version increments need to carefully planned and managed at a project
+that ABI version increments need to be carefully planned and managed at a project
 level.
 
 Major ABI versions are therefore declared typically aligned with an LTS release
-and is then supported some number of subsequent releases, shared across all
+and are then supported for some number of subsequent releases, shared across all
 libraries. This means that a single project level ABI version, reflected in all
 individual library's soname, library filenames and associated version maps
 persists over multiple releases.
@@ -128,7 +128,7 @@ Versioning Macros
 When a symbol is exported from a library to provide an API, it also provides a
 calling convention (ABI) that is embodied in its name, return type and
 arguments. Occasionally that function may need to change to accommodate new
-functionality or behavior. When that occurs, it is may be required to allow for
+functionality or behavior. When that occurs, it may be required to allow for
 backward compatibility for a time with older binaries that are dynamically
 linked to the DPDK.
 
@@ -140,16 +140,16 @@ library so that older binaries need not be immediately recompiled.
 The macros are:
 
 * ``RTE_VERSION_SYMBOL(ver, type, name, args)``: Creates a symbol version table
-  entry binding symbol ``<name>@DPDK_<ver>`` to the internal function name
-  ``<name>_v<ver>``.
+  entry binding symbol ``<n>@DPDK_<ver>`` to the internal function name
+  ``<n>_v<ver>``.
 
 * ``RTE_DEFAULT_SYMBOL(ver, type, name, args)``: Creates a symbol version entry
-  instructing the linker to bind references to symbol ``<name>`` to the internal
-  symbol ``<name>_v<ver>``.
+  instructing the linker to bind references to symbol ``<n>`` to the internal
+  symbol ``<n>_v<ver>``.
 
 * ``RTE_VERSION_EXPERIMENTAL_SYMBOL(type, name, args)``:  Similar to RTE_VERSION_SYMBOL
   but for experimental API symbols. The macro is used when a symbol matures
-  to become part of the stable ABI, to provide an alias to experimental
+  to become part of the stable ABI, to provide an alias to the experimental version
   until the next major ABI version.
 
 .. _example_abi_macro_usage:
@@ -276,7 +276,7 @@ versioning, in the ``meson.build`` file we add the following
 
    use_function_versioning = true
 
-at the start of the head of the file. This will indicate to the tool-chain to
+at the start of the file. This will indicate to the tool-chain to
 enable the function version macros when building.
 
 
@@ -336,7 +336,7 @@ and ``DPDK_22`` version nodes.
 
 .. code-block:: c
 
-   #include <rte_compat.h>;
+   #include <rte_compat.h>
 
    /*
     * Create an acl context object for apps to
@@ -357,7 +357,7 @@ and ``DPDK_22`` version nodes.
 Deprecating part of a public API
 ________________________________
 
-Lets assume that you've done the above updates, and in preparation for the next
+Let's assume that you've done the above updates, and in preparation for the next
 major ABI version you decide you would like to retire the old version of the
 function. After having gone through the ABI deprecation announcement process,
 removal is easy.
-- 
2.51.0