Skip to content

doc: changes to abi policy introducing major abi versions

Ray Kinsella dpdk-dev 11 versions – Applied

Status from this message: Applied, thanks

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v11 Latest3 patches 2 repliesApplied
  2. v103 patches 0 repliesSuperseded
  3. v94 patches 5 repliesSuperseded
Earlier versions · 8
VersionPostedPatchesRepliesStatus
v84 patches14 repliesSuperseded
v74 patches6 repliesSuperseded
v64 patches14 repliesSuperseded
v54 patches0 repliesSuperseded
v44 patches6 repliesSuperseded
v34 patches3 repliesSuperseded
v23 patches0 repliesSuperseded
v11 patch2 repliesSuperseded

Patches in v11 Applied

#Subject and filesSizeRepliesApplied
1/3doc: separate versioning.rst into version and policyMAINTAINERS doc/guides/contributing/abi_policy.rst doc/guides/contributing/abi_versioning.rst +4 more+608 -6000 replies
2/3doc: changes to abi policy introducing major abi versionsdoc/guides/contributing/abi_policy.rst doc/guides/contributing/img/abi_stability_policy.svg doc/guides/contributing/img/what_is_an_abi.svg +1 more+1687 -910 replies
3/3doc: updates to versioning guide for abi versionsdoc/guides/contributing/abi_policy.rst doc/guides/contributing/abi_versioning.rst doc/guides/contributing/patches.rst +1 more+183 -940 replies

Reviews trailers per patch

All 3 patches have a Reviewed-by or Acked-by.

PatchJohn McnamaraStephen HemmingerThomas Monjalon
1/3A-b A-b
2/3A-b A-b A-b
3/3A-b A-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes. Scroll the table sideways for all 3 reviewers.

Read the v11 thread

Cover letter [dpdk-dev] [PATCH v11 0/3] doc: changes to abi policy introducing major abi versions

TL;DR abbreviation:
A major ABI version that all DPDK releases during an agreed period support. ABI versioning is managed at a project-level, in place of library-level management. ABI changes to add new features are permitted, as long as ABI compatibility with the major ABI version is maintained.

Detail:
This patch introduces major ABI versions, initally released aligned with the LTS release and maintained for one year through subsequent releases. The intention is that the one year abi support period, will then be reviewed after the initial year with the intention of lengthening the period for the next ABI version and declaring new major ABI versions less frequently.

ABI changes that preserve ABI compatibility with the major ABI version are permitted in subsequent releases. ABI changes, follow similar approval rules as before with the additional gate of now requiring technical board approval. The merging and release of ABI breaking changes would now be pushed to the declaration of the next major ABI version.

This change encourages developers to maintain ABI compatibility with the major ABI version, by promoting a permissive culture around those changes that preserve ABI compatibility. This approach begins to align DPDK with those projects that declare major ABI versions (e.g. version 2.x, 3.x) and support those versions for some period, typically two years or more.

To provide an example of how this might work in practice:

* DPDK v20 is declared as the supported ABI version for one year, aligned with the DPDK v19.11 (LTS) release. All library sonames are updated to reflect the new ABI version, e.g. librte_eal.so.20, librte_acl.so.20...
* DPDK v20.02 .. v20.08 releases are ABI compatible with the DPDK v20 ABI. ABI changes are permitted from DPDK v20.02 onwards, with the condition that ABI compatibility with DPDK v20 is preserved.
* DPDK v21 is declared as the new supported ABI version for two years, aligned with the DPDK v20.11 (LTS) release. The DPDK v20 ABI is now depreciated, library sonames are updated to v21 and ABI compatibility breaking changes may be introduced.

v11
* Neglected to rebase the v10 onto origin/master, fixed in v11.

v10
* Fixed the upwording on experimental libraries in summary.

v9
* Loosened up word around when new major ABI's are declared. (as suggested by Thomas Monjalon and agreed at the Techboard)

v8
* Fixed intermediate build warnings, figure annotations and typo's. (as suggested by John McNamara).

v7
* PNGs are now SVG. Some additional clarifications. Fixed typos and grammatical errors. (as suggested by Thomas Monjalon and David Marchand)

v6
* Added figure to abi_policy.rst, comparing and contrasting the DPDK abi and api. (as suggested by Aaron Conole)

v5
* Added figure to abi_policy.rst, mapping abi versions and abi compatibility to DPDK releases. (as suggested by Neil Horman)

v4
* Removed changes to stable.rst, fixed typos and clarified the ABI policy "warning".

v3
* Added myself as the maintainer of the ABI policy.
* Updated the policy and versioning guides to use the year of the LTS+1 (e.g. v20), as the abi major version number.

v2
* Restructured the patch into 3 patches:
1. Splits the original versioning document into an ABI policy document and ABI versioning document.
2. Add changes to the policy document introducing major ABI versions.
3. Fixes up the versioning document in light of major ABI versioning.
* Reduces the initial ABI stability from two years to one year, with a review after the first year.
* Adds detail around ABI version handling for experimental libraries.
* Adds detail around chain of responsility for removing deprecated symbols.

Ray Kinsella (3):
doc: separate versioning.rst into version and policy
doc: changes to abi policy introducing major abi versions
doc: updates to versioning guide for abi versions

 MAINTAINERS                                        |    4 +
 doc/guides/contributing/abi_policy.rst             |  327 ++++++
 doc/guides/contributing/abi_versioning.rst         |  521 ++++++++++
 .../contributing/img/abi_stability_policy.svg      | 1059 ++++++++++++++++++++
 doc/guides/contributing/img/what_is_an_abi.svg     |  382 +++++++
 doc/guides/contributing/index.rst                  |    3 +-
 doc/guides/contributing/patches.rst                |    6 +-
 doc/guides/contributing/stable.rst                 |   12 +-
 doc/guides/contributing/versioning.rst             |  597 -----------
 doc/guides/rel_notes/deprecation.rst               |    6 +-
 10 files changed, 2305 insertions(+), 612 deletions(-)
 create mode 100644 doc/guides/contributing/abi_policy.rst
 create mode 100644 doc/guides/contributing/abi_versioning.rst
 create mode 100644 doc/guides/contributing/img/abi_stability_policy.svg
 create mode 100644 doc/guides/contributing/img/what_is_an_abi.svg
 delete mode 100644 doc/guides/contributing/versioning.rst
Signature · 1 line
2.7.4