DPDK patches and discussions
 help / color / mirror / Atom feed
From: Ray Kinsella <mdr@ashroe.eu>
To: Thomas Monjalon <thomas@monjalon.net>
Cc: dev@dpdk.org, stephen@networkplumber.org,
	bruce.richardson@intel.com, ferruh.yigit@intel.com,
	konstantin.ananyev@intel.com, jerinj@marvell.com,
	olivier.matz@6wind.com, nhorman@tuxdriver.com,
	maxime.coquelin@redhat.com, john.mcnamara@intel.com,
	marko.kovacevic@intel.com, hemant.agrawal@nxp.com,
	ktraynor@redhat.com, aconole@redhat.com
Subject: Re: [dpdk-dev] [PATCH v6 2/4] doc: changes to abi policy introducing major abi versions
Date: Fri, 25 Oct 2019 13:45:51 +0100	[thread overview]
Message-ID: <37defad4-f2d2-9cf0-51b3-4fd2cbedee61@ashroe.eu> (raw)
In-Reply-To: <10410603.iXVFKWJQZn@xps>



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 <mdr@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.

  parent reply	other threads:[~2019-10-25 12:46 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-27 16:54 [dpdk-dev] [PATCH v6 0/4] " Ray Kinsella
2019-09-27 16:54 ` [dpdk-dev] [PATCH v6 1/4] doc: separate versioning.rst into version and policy Ray Kinsella
2019-10-01 12:50   ` Hemant Agrawal
2019-10-01 13:19     ` Ray Kinsella
2019-10-21  9:53   ` Thomas Monjalon
2019-10-25 11:36     ` Ray Kinsella
2019-09-27 16:54 ` [dpdk-dev] [PATCH v6 2/4] doc: changes to abi policy introducing major abi versions Ray Kinsella
2019-10-15 15:11   ` David Marchand
2019-10-25 11:43     ` Ray Kinsella
2019-10-24  0:43   ` Thomas Monjalon
2019-10-25  9:10     ` Ray Kinsella
2019-10-28 10:02       ` Thomas Monjalon
2019-10-25 12:45     ` Ray Kinsella [this message]
2019-09-27 16:54 ` [dpdk-dev] [PATCH v6 3/4] doc: updates to versioning guide for " Ray Kinsella
2019-09-27 16:54 ` [dpdk-dev] [PATCH v6 4/4] doc: add maintainer for abi policy Ray Kinsella
2019-10-21  9:50 ` [dpdk-dev] [PATCH v6 0/4] doc: changes to abi policy introducing major abi versions Thomas Monjalon
2019-10-21 10:10   ` Ray Kinsella
2019-10-21 14:38     ` Thomas Monjalon
2019-10-22  8:12       ` Ray Kinsella

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=37defad4-f2d2-9cf0-51b3-4fd2cbedee61@ashroe.eu \
    --to=mdr@ashroe.eu \
    --cc=aconole@redhat.com \
    --cc=bruce.richardson@intel.com \
    --cc=dev@dpdk.org \
    --cc=ferruh.yigit@intel.com \
    --cc=hemant.agrawal@nxp.com \
    --cc=jerinj@marvell.com \
    --cc=john.mcnamara@intel.com \
    --cc=konstantin.ananyev@intel.com \
    --cc=ktraynor@redhat.com \
    --cc=marko.kovacevic@intel.com \
    --cc=maxime.coquelin@redhat.com \
    --cc=nhorman@tuxdriver.com \
    --cc=olivier.matz@6wind.com \
    --cc=stephen@networkplumber.org \
    --cc=thomas@monjalon.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).