Hi Thomas, QQ - So is there really a 'no png' rule, because we have lots of them in the documentation?
root@rkinsell-MOBL2:.../rkinsell/dpdk# find doc/ -name "*.png" | wc -l 61 root@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 <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. > > [...] >> +#. 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. > >
