From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <bernard.iremonger@intel.com>
Received: from mga03.intel.com (mga03.intel.com [134.134.136.65])
 by dpdk.org (Postfix) with ESMTP id 6CB315A15
 for <dev@dpdk.org>; Wed, 21 Jan 2015 11:13:53 +0100 (CET)
Received: from fmsmga002.fm.intel.com ([10.253.24.26])
 by orsmga103.jf.intel.com with ESMTP; 21 Jan 2015 02:09:45 -0800
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.09,440,1418112000"; d="scan'208";a="665139165"
Received: from irsmsx104.ger.corp.intel.com ([163.33.3.159])
 by fmsmga002.fm.intel.com with ESMTP; 21 Jan 2015 02:13:44 -0800
Received: from irsmsx108.ger.corp.intel.com ([169.254.11.64]) by
 IRSMSX104.ger.corp.intel.com ([169.254.5.229]) with mapi id 14.03.0195.001;
 Wed, 21 Jan 2015 10:13:43 +0000
From: "Iremonger, Bernard" <bernard.iremonger@intel.com>
To: Neil Horman <nhorman@tuxdriver.com>
Thread-Topic: [dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation
Thread-Index: AQHQNPbF5+lfvcEZ20mIY9QbyQPTypzKWLAg
Date: Wed, 21 Jan 2015 10:13:42 +0000
Message-ID: <8CEF83825BEC744B83065625E567D7C2049D943D@IRSMSX108.ger.corp.intel.com>
References: <1419109299-9603-1-git-send-email-nhorman@tuxdriver.com>
 <1421788679-9433-1-git-send-email-nhorman@tuxdriver.com>
 <1421788679-9433-4-git-send-email-nhorman@tuxdriver.com>
In-Reply-To: <1421788679-9433-4-git-send-email-nhorman@tuxdriver.com>
Accept-Language: en-GB, en-US
Content-Language: en-US
X-MS-Has-Attach: 
X-MS-TNEF-Correlator: 
x-originating-ip: [163.33.239.182]
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
Cc: "dev@dpdk.org" <dev@dpdk.org>
Subject: Re: [dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: patches and discussions about DPDK <dev.dpdk.org>
List-Unsubscribe: <http://dpdk.org/ml/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <http://dpdk.org/ml/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Wed, 21 Jan 2015 10:13:53 -0000

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> Sent: Tuesday, January 20, 2015 9:18 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation
>=20
> Adding a document describing rudimentary ABI policy and adding notice spa=
ce for any deprecation
> announcements
>=20
> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> CC: Thomas Monjalon <thomas.monjalon@6wind.com>
> CC: "Richardson, Bruce" <bruce.richardson@intel.com>
>=20
> ---
> Change notes:
>=20
> v5) Updated documentation to add notes from Thomas M.
>=20
> v6) Moved abi.txt to guides/rel_notes/abi.rst
> ---
>  doc/guides/rel_notes/abi.rst | 38 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>  create mode 100644 doc/guides/rel_notes/abi.rst

Hi Neil,

The file doc/guides/rel_notes/index.rst  should be modified to include "abi=
" so that the abi.rst file is included in the release notes.

>=20
> diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/abi.rst =
new file mode 100644 index
> 0000000..98ac19d
> --- /dev/null
> +++ b/doc/guides/rel_notes/abi.rst
> @@ -0,0 +1,38 @@
> +ABI policy
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +	ABI versions are set at the time of major release labeling, and ABI
> +may change multiple times between the last labeling and the HEAD label
> +of the git tree without warning
> +
> +	ABI versions, once released are available until such time as their
> +deprecation has been noted here for at least one major release cycle,
> +after it has been tagged.  E.g. the ABI for DPDK 1.8 is shipped, and
> +then the decision to remove it is made during the development of DPDK
> +1.9.  The decision will be recorded here, shipped with the DPDK 1.9
> +release, and actually removed when DPDK
> +1.10 ships.
> +
> +	ABI versions may be deprecated in whole, or in part as needed by a
> +given update.
> +
> +	Some ABI changes may be too significant to reasonably maintain
> +multiple versions of.  In those events ABI's may be updated without
> +backward compatibility provided.  The requirements for doing so are:

The #.  Syntax could be used for numbered lists

> +	1) At least 3 acknoweldgements of the need on the dpdk.org

A blank line is needed otherwise the text will concatenate.

> +	2) A full deprecation cycle must be made to offer downstream consumers
> +sufficient warning of the change.  E.g. if dpdk 2.0 is under
> +development when the change is proposed, a deprecation notice must be
> +added to this file, and released with dpdk 2.0.  Then the change may be =
incorporated for dpdk 2.1

A blank line is needed otherwise the text will concatenate.

> +	3) The LIBABIVER variable in the makefilei(s) where the ABI changes
> +are incorporated must be incremented in parallel with the ABI changes
> +themselves

A blank line is needed otherwise the text will concatenate.
> +
> +	Note that the above process for ABI deprecation should not be
> +undertaken lightly.  ABI stability is extreemely important for
> +downstream consumers of the DPDK, especially when distributed in shared
> +object form.  Every effort should be made to preserve ABI whenever
> +possible.  For instance, reorganizing public structure field for
> +astetic or readability purposes should be avoided as it will cause ABI
> +breakage.  Only significant (e.g. performance) reasons should be seen as=
 cause to alter ABI.
> +
> +Deprecation Notices
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> --
> 2.1.0
Regards,

Bernard.