[dpdk-dev] [PATCH v6 2/4] doc: changes to abi policy introducing major abi versions

[Thomas Monjalon]

27/09/2019 18:54, Ray Kinsella:
> This policy change introduces major ABI versions, these are
> declared every year, typically aligned with the LTS release
> and are supported by subsequent releases in the following year.

No, the ABI number may stand for more than one year.

> This change is intended to improve ABI stabilty for those projects
> consuming DPDK.
> 
> Signed-off-by: Ray Kinsella <mdr at ashroe.eu>
> ---
>  doc/guides/contributing/abi_policy.rst             | 321 +++++++++++++++------
>  .../contributing/img/abi_stability_policy.png      | Bin 0 -> 61277 bytes
>  doc/guides/contributing/img/what_is_an_abi.png     | Bin 0 -> 151683 bytes

As an Open Source project, binary files are rejected :)
Please provide the image source as SVG if the diagram is really required.

[...] 
> +#. Major ABI versions are declared every **year** and are then supported for one
> +   year, typically aligned with the :ref:`LTS release <stable_lts_releases>`.

As discussed on the cover letter, please avoid making "every year" cadence, the rule.

> +#. The ABI version is managed at a project level in DPDK, with the ABI version
> +   reflected in all :ref:`library's soname <what_is_soname>`.

Should we make clear here that an experimental ABI change has no impact
on the ABI version number?

> +#. The ABI should be preserved and not changed 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.
> +#. Libraries or APIs marked as :ref:`Experimental <experimental_apis>` are not
> +   considered part of an ABI version and may change without constraint.
> +#. 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.
> +
> +.. note::
> +
> +   In 2019, the DPDK community stated it's intention to move to ABI stable
> +   releases, over a number of release cycles. Beginning with maintaining ABI
> +   stability through one year of DPDK releases starting from DPDK 19.11.

There is no verb in this sentence.

> +   This
> +   policy will be reviewed in 2020, with intention of lengthening the stability
> +   period.

> +What is an ABI version?
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +An ABI version is an instance of a library's ABI at a specific release. Certain
> +releases are considered by the community to be milestone releases, the yearly
> +LTS for example. Supporting those milestone release's ABI for some number of
> +subsequent releases is desirable to facilitate application upgrade. Those ABI
> +version's aligned with milestones release are therefore called 'ABI major
> +versions' and are supported for some number of releases.

If you understand this paragraph, please raise your hand :)

> +More details on major ABI version can be found in the :ref:`ABI versioning
> +<major_abi_versions>` guide.
>  
>  The DPDK ABI policy
> -~~~~~~~~~~~~~~~~~~~
> +-------------------
> +
> +A major ABI version is declared every year, aligned with that year's LTS
> +release, e.g. v19.11. This ABI version is then supported for one year by all
> +subsequent releases within that time period, until the next LTS release, e.g.
> +v20.11.

Again, the "one year" limit should not be documented as a general rule.

> +At the declaration of a major ABI version, major version numbers encoded in
> +libraries soname's are bumped to indicate the new version, with the minor
> +version reset to ``0``. An example would be ``librte_eal.so.20.3`` would become
> +``librte_eal.so.21.0``.
>  
> +The ABI may then change multiple times, without warning, between the last major
> +ABI version increment and the HEAD label of the git tree, with the condition
> +that ABI compatibility with the major ABI version is preserved and therefore
> +soname's 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.20.1`` would indicate the first ABI compatible DPDK
> +release, following the declaration of the new major ABI version ``20``.

I don't understand the benefit of having a minor ABI version number.
Can we just have v20 and v21 as we discussed in the techboard?
Is it because an application linked with v20.2 cannot work with v20.1?

If we must have a minor number, I suggest a numbering closer to release numbers:
	release 19.11 -> ABI 19.11
	release 20.02 -> ABI 19.14
	release 20.05 -> ABI 19.17
	release 20.08 -> ABI 19.20
It shows the month number as if the first year never finishes.
And when a new ABI is declared, release and ABI versions are the same:
	release 20.11 -> ABI 20.11


> +ABI versions, are supported by each release until such time as the next major
> +ABI version is declared. At that time, the deprecation of the previous major ABI
> +version will be noted in the Release Notes with guidance on individual symbol
> +depreciation and upgrade notes provided.

I suggest a rewording:
"
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 give details about all ABI changes.
"

[...]
> +   - The acknowledgment of a member of the technical board, as a delegate of the
> +     `technical board <https://core.dpdk.org/techboard/>`_ acknowledging the
> +     need for the ABI change, is also mandatory.

Only one? What about 3 members minimum?

[...]
> +#. If a newly proposed API functionally replaces an existing one, when the new
> +   API becomes non-experimental, then the old one is marked with
> +   ``__rte_deprecated``.
> +
> +    - The depreciated 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.
> +
> +    - 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.

Having too many responsibles look like nobody is really responsible.
I would tend to think that only the maintainer is responsible,
but he can ask for help.