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

[Thomas Monjalon <thomas@monjalon.net>]

I'm sorry I still have some comments.
But on the positive side, you can see that I carefuly read this doc.

05/11/2019 16:24, Ray Kinsella:
> +#. 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 earlier, a major ABI version can be declared less often
than one year in the future.
An ABI is supported more than one year, because of the LTS branches.
That's why I propose to replace with this sentence:
"
Major ABI versions are declared regularly and are then supported for
at least one year, typically aligned with the :ref:`LTS release <stable_lts_releases>`.
"

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

Yes, even the experimental libraries should have the same version,
with the minor number incremented at each release.
(just a comment to change a policy at the end of this patch)

> +   In 2019, the DPDK community stated its intention to move to ABI stable
> +   releases, over a number of release cycles. This change begins with
> +   maintaining ABI stability through one year of DPDK releases starting from
> +   DPDK 19.11. This policy will be reviewed in 2020, with intention of
> +   lengthening the stability period.

Great, the schedule is clear here.

> +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.

Let's reword like this:
"
A new major ABI version can be declared when a new LTS branch is started,
e.g. ABI 19 for DPDK 19.11.0.
This major ABI version is then supported until the next one,
e.g. ABI 20 for DPDK 20.11.0.
All ABI changes must be detailed in the release notes.
"

> +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.20.3`` would become
> +``librte_eal.so.21.0``.
>  
> +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``.
>  
> +An ABI version is supported in all new releases until the next major ABI version
> +is declared.

This sentence is repetitive.

> When changing the major ABI version, the release notes will detail
> +all ABI changes.

I suggest to move and reword this sentence above (as in my above reword).

> +   ABI breakages due to changes such as reorganizing public
> +   structure fields for aesthetic or readability purposes should be avoided.

Why it should be avoided?
If the ABI is broken anyway, I don't see any reason to not break it more.

> +#. 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
> +   at the declaration of the next major ABI version.

I missed that in discussions.
I thought we wanted to wait for the next major ABI.
If we allow NEXT_ABI ifdef, we will have 2 DPDK versions
(stable and next ABI) to test.

> +Libraries marked as ``experimental`` are entirely not considered part of an ABI
> +version, and may change without warning at any time. Experimental libraries
> +always have a major version of ``0`` to indicate they exist outside of
> +ABI Versioning, with the minor version incremented with each ABI change
> +to library.

It means not all libraries will have the same ABI version.
It is contrary of "ABI version is managed at a project level",
and I don't see a real benefit of a different version number.
Anyway, some experimental functions can live inside a library
with a stable ABI version number.