On 24/10/2019 01:43, Thomas Monjalon wrote:
> 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.
ok, I will remove the reference to one year here.
Just on a point of order, what was approved by the technical board was `one
year`, initially.
So the ABI Policy at this point in time is stability for `one year`.
I tried to make the `one year` point in as few places as possible.
Simply to reduce the rework later, when we lengthen the abi support period.
I also include a note up front, making it abundantly clear the intention to
lengthen the support period, as follows.
"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. This
policy will be reviewed in 2020, with intention of lengthening the stability
period."
>
>> This change is intended to improve ABI stabilty for those projects
>> consuming DPDK.
>>
>> Signed-off-by: Ray Kinsella <m...@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.
ACK, done
>
> [...]
>> +#. 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.
It's very hard to remove this one, what should can we say instead?
#. Major ABI versions are declared on some cadence and are then supported for
some
period unknown, typically aligned with the `LTS release
<stable_lts_releases>`.
>
>> +#. 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?
Absolutely, see four points below.
#. Libraries or APIs marked as :ref:`Experimental <experimental_apis>` are not
considered part of an ABI version and may change without constraint.
>> +#. 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.
ACK, done.
>
>> + 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 :)
We can simplify as follows.
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
example. The ABI of a milestone release may be designated as a 'major ABI
version', where this ABI version is then supported for some number of subsequent
releases.
Major ABI version support in subsequent releases facilitates application
upgrade, by enabling applications built against the milestone release, to
upgrade to subsequent releases of the library without a rebuild.
>
>> +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.
As I said above, it's not obvious to me what I would say in its place.
Can we leave as is until the community agree to lengthen the period?
>
>> +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?
You need to have minor versions for forward compatibility.
So let's say v20 is the major ABI in v19.11.
However a new function `rte_foobar` get's added in DPDK v20.02.
`rte_foobar` is no longer experimental.
I write a new application `funet` what _needs_ `rte_foobar`.
The only way I can tell I have gotten the right library version,
to satisfy `funet`s dependencies is the minor version number.
In this case `funet`s author can also have a reasonable expectation,
that `rte_foobar` will become part of the next `major ABI version`.
>
> 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
What was agreed at the technical board is that DPDK v19.11 is ABI v20.
Minor numbers are usually incremental, and release numbers do not need
to co-relate with ABI version numbers.
We previously discussed that
v20.1 = LTS + 1 release = v20.02
v20.2 = LTS + 2 release = v20.05
All that said.
I am very eager not to get into describing release management in the ABI policy.
ABI policy is enough to describe with detail DPDKs release management also.
>
>
>> +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.
> "
ACK, happy to change, much of that wording was reuse from the old policy.
> [...]
>> + - 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?
My feeling is that that three would become a real headache over time.
Limit the techboards ability to scale, with each change requiring three ACKs
from them.
I am happy to change it, if you feel strongly.
>
> [...]
>> +#. 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.
Others had specifically asked that the chain of responsibility be very clear,
so that all the burden for excising redundant code does not fall
automatically on the maintainer.
