From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 05954A2EFC for ; Tue, 15 Oct 2019 17:11:47 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id D3CC11EB3F; Tue, 15 Oct 2019 17:11:46 +0200 (CEST) Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by dpdk.org (Postfix) with ESMTP id E96A91E9C2 for ; Tue, 15 Oct 2019 17:11:45 +0200 (CEST) Received: from mail-ua1-f70.google.com (mail-ua1-f70.google.com [209.85.222.70]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 463B2C057F20 for ; Tue, 15 Oct 2019 15:11:45 +0000 (UTC) Received: by mail-ua1-f70.google.com with SMTP id y4so4765966uaa.17 for ; Tue, 15 Oct 2019 08:11:45 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=bj5CSQ1Ai37KGCtHyZj1uFFkQgaKAH9H/YxZcNLn+RE=; b=D+Zl7W5jJE+lcntZi4lWW67g37X61jXwhAl0hRJk+Kp2TIk74q1nMoZhznCk9mjpAM l5DF6GMX0xgmcOoCpLtGseEzAPhZW7kNP+4DaQaKEGPe3Ehxyt0BfZcDibiEmUPRZ3rj PlQ2QKT8lRw83C+89T2DRxS1MrIE+xRIa/zR7w1Sa2L7ptJZ5znFg6gD1zfYka97AgSE c97HRf5/kxsjC5Yu1T7rDQNjOcV6LvC+c8PG+mNfJYezZuvH5X33fGwSj3e4M/c7Ho+o AWGnHTvKH17q53gWwnqPbWL93SHOZEWzwXO7c9omWxkltaZ9D6eWHXZtyVO8TEuB9hIh VIvQ== X-Gm-Message-State: APjAAAVOwlJGesC6KzqOYXsNA4Nzpc8uXDDQpRqP1JFg92ZDIVzrfj8Q I+C1H+BpH4n4cueTHShDF8iizxzOv4BTzBzv58+YuYisHsaBMiSm6XurLZHKgyvW32Qjj7z91IX JVTfdGoym7h5q9YIvGk0= X-Received: by 2002:a67:e88b:: with SMTP id x11mr20529157vsn.180.1571152304305; Tue, 15 Oct 2019 08:11:44 -0700 (PDT) X-Google-Smtp-Source: APXvYqzc6N95ALowiiysSLvdm4yuN30GT52XJ95702hIV1nTidLHj8nIFJPkFgQ4kw0J4Tj3GX8u0kQ/KDXa/wM1h84= X-Received: by 2002:a67:e88b:: with SMTP id x11mr20529123vsn.180.1571152303729; Tue, 15 Oct 2019 08:11:43 -0700 (PDT) MIME-Version: 1.0 References: <1569603283-1857-1-git-send-email-mdr@ashroe.eu> <1569603283-1857-3-git-send-email-mdr@ashroe.eu> In-Reply-To: <1569603283-1857-3-git-send-email-mdr@ashroe.eu> From: David Marchand Date: Tue, 15 Oct 2019 17:11:32 +0200 Message-ID: To: Ray Kinsella Cc: dev , Thomas Monjalon , Stephen Hemminger , Bruce Richardson , "Yigit, Ferruh" , "Ananyev, Konstantin" , Jerin Jacob Kollanukkaran , Olivier Matz , Neil Horman , Maxime Coquelin , "Mcnamara, John" , "Kovacevic, Marko" , Hemant Agrawal , Kevin Traynor , Aaron Conole Content-Type: text/plain; charset="UTF-8" Subject: Re: [dpdk-dev] [PATCH v6 2/4] doc: changes to abi policy introducing major abi versions X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Hello, On Fri, Sep 27, 2019 at 6:55 PM Ray Kinsella wrote: > > 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. > This change is intended to improve ABI stabilty for those projects > consuming DPDK. I spotted a few typos (far from being a complete report of them). We can wait later in the release to fix those, but it would be more efficient if native speakers proofread those docs. John and Marko? Volunteers? Thanks. > > Signed-off-by: Ray Kinsella > --- > 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 > doc/guides/contributing/stable.rst | 12 +- > 4 files changed, 241 insertions(+), 92 deletions(-) > create mode 100644 doc/guides/contributing/img/abi_stability_policy.png > create mode 100644 doc/guides/contributing/img/what_is_an_abi.png > > diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst > index 55bacb4..8862d24 100644 > --- a/doc/guides/contributing/abi_policy.rst > +++ b/doc/guides/contributing/abi_policy.rst > @@ -1,33 +1,46 @@ > .. SPDX-License-Identifier: BSD-3-Clause > - Copyright 2018 The DPDK contributors > + Copyright 2019 The DPDK contributors > > -.. abi_api_policy: > +.. _abi_policy: > > -DPDK ABI/API policy > -=================== > +ABI Policy > +========== > > Description > ----------- > > -This document details some methods for handling ABI management in the DPDK. > +This document details the management policy that ensures the long-term stability > +of the DPDK ABI and API. > > General Guidelines > ------------------ > > -#. Whenever possible, ABI should be preserved > -#. ABI/API may be changed with a deprecation process > -#. The modification of symbols can generally be managed with versioning > -#. Libraries or APIs marked in ``experimental`` state may change without constraint > -#. New APIs will be marked as ``experimental`` for at least one release to allow > - any issues found by users of the new API to be fixed quickly > -#. The addition of symbols is generally not problematic > -#. The removal of symbols generally is an ABI break and requires bumping of the > - LIBABIVER macro > -#. Updates to the minimum hardware requirements, which drop support for hardware which > - was previously supported, should be treated as an ABI change. > - > -What is an ABI > -~~~~~~~~~~~~~~ > +#. Major ABI versions are declared every **year** and are then supported for one > + year, typically aligned with the :ref:`LTS release `. > +#. The ABI version is managed at a project level in DPDK, with the ABI version > + reflected in all :ref:`library's soname `. > +#. The ABI should be preserved and not changed lightly. ABI changes must follow > + the outlined :ref:`deprecation process `. > +#. The addition of symbols is generally not problematic. The modification of > + symbols is managed with :ref:`ABI Versioning `. > +#. The removal of symbols is considered an :ref:`ABI breakage `, > + once approved these will form part of the next ABI version. > +#. Libraries or APIs marked as :ref:`Experimental ` are not > + considered part of an ABI version and may change without constraint. > +#. Updates to the :ref:`minimum hardware requirements `, 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 its? > + releases, over a number of release cycles. Beginning with maintaining ABI > + stability through one year of DPDK releases starting from DPDK 19.11. This sentence without a verb? > + policy will be reviewed in 2020, with intention of lengthening the stability > + period. > + > +What is an ABI? > +~~~~~~~~~~~~~~~ > > An ABI (Application Binary Interface) is the set of runtime interfaces exposed > by a library. It is similar to an API (Application Programming Interface) but > @@ -39,30 +52,80 @@ Therefore, in the case of dynamic linking, it is critical that an ABI is > preserved, or (when modified), done in such a way that the application is unable > to behave improperly or in an unexpected fashion. > > +.. _figure_what_is_an_abi: > + > +.. figure:: img/what_is_an_abi.* > + > +*Figure 1. Illustration of DPDK API and ABI .* > > -ABI/API Deprecation > -------------------- > + > +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? milestone releases > +versions' and are supported for some number of releases. > + > +More details on major ABI version can be found in the :ref:`ABI versioning > +` 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. > + > +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``. > > -ABI versions are set at the time of major release labeling, and the ABI may > -change multiple times, without warning, between the last release label and the > -HEAD label of the git tree. > +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. > > -ABI versions, once released, are available until such time as their > -deprecation has been noted in the Release Notes for at least one major release > -cycle. For example consider the case where the ABI for DPDK 2.0 has been > -shipped and then a decision is made to modify it during the development of > -DPDK 2.1. The decision will be recorded in the Release Notes for the DPDK 2.1 > -release and the modification will be made available in the DPDK 2.2 release. > +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``. > > -ABI versions may be deprecated in whole or in part as needed by a given > -update. > +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. deprecation? > > -Some ABI changes may be too significant to reasonably maintain multiple > -versions. In those cases ABI's may be updated without backward compatibility > -being provided. The requirements for doing so are: > +.. _figure_abi_stability_policy: > + > +.. figure:: img/abi_stability_policy.* > + > +*Figure 2. Mapping of new ABI versions and ABI version compatibility to DPDK > +releases.* > + > +.. _abi_changes: > + > +ABI Changes > +~~~~~~~~~~~ > + > +The ABI may still change after the declaration of a major ABI version, that is > +new APIs may be still added or existing APIs may be modified. > + > +.. Warning:: > + > + Note that, this policy details the method by which the ABI may be changed, > + with due regard to preserving compatibility and observing depreciation deprecation? > + notices. This process however should not be undertaken lightly, as a general > + rule ABI stability is extremely important for downstream consumers of DPDK. > + The ABI should only be changed for significant reasons, such as performance > + enhancements. ABI breakages due to changes such as reorganizing public > + structure fields for aesthetic or readability purposes should be avoided. > + > +The requirements for changing the ABI are: [snip] -- David Marchand