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

[Ray Kinsella]

Hi Thomas, 

QQ - So is there really a 'no png' rule, because we have lots of them in the documentation?

root at rkinsell-MOBL2:.../rkinsell/dpdk# find doc/ -name "*.png" | wc -l
61
root at rkinsell-MOBL2:.../rkinsell/dpdk# find doc/ -name "*.svg" | wc -l
116

I am looking at recreating the images as SVG, but if it comes down to it - would they be ok to go as PNGs?

Thanks, 

Ray K

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