DPDK patches and discussions
 help / color / mirror / Atom feed
From: "O'driscoll, Tim" <tim.o'driscoll@intel.com>
To: Neil Horman <nhorman@tuxdriver.com>,
	"Iremonger, Bernard" <bernard.iremonger@intel.com>
Cc: "dev@dpdk.org" <dev@dpdk.org>
Subject: Re: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
Date: Tue, 20 Jan 2015 14:32:45 +0000
Message-ID: <26FA93C7ED1EAA44AB77D62FBE1D27BA54CA6491@IRSMSX102.ger.corp.intel.com> (raw)
In-Reply-To: <20150120142401.GA18449@hmsreliant.think-freely.org>

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> Sent: Tuesday, January 20, 2015 2:24 PM
> To: Iremonger, Bernard
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
> 
> On Tue, Jan 20, 2015 at 01:37:35PM +0000, Iremonger, Bernard wrote:
> > > -----Original Message-----
> > > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Thomas
> Monjalon
> > > Sent: Tuesday, January 20, 2015 7:15 AM
> > > To: Neil Horman
> > > Cc: dev@dpdk.org
> > > Subject: Re: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
> > >
> > > Thank you Neil for writing this document.
> > > This is a really important change in DPDK.
> > > It would be very good to have comments or acknowledgement from
> several developpers. This policy
> > > would be enforced by having several Acked-by lines.
> > >
> > >
> > > 2015-01-16 10:33, Neil Horman:
> > > > Adding a document describing rudimentary ABI policy and adding notice
> > > > space for any deprecation announcements
> > > >
> > > > Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> > > > CC: Thomas Monjalon <thomas.monjalon@6wind.com>
> > > > CC: "Richardson, Bruce" <bruce.richardson@intel.com>
> > > >
> > > > ---
> > > > Change notes:
> > > >
> > > > v5) Updated documentation to add notes from Thomas M.
> > > > ---
> > > >  doc/abi.txt | 36 ++++++++++++++++++++++++++++++++++++
> > > >  1 file changed, 36 insertions(+)
> > > >  create mode 100644 doc/abi.txt
> > > >
> > > > diff --git a/doc/abi.txt b/doc/abi.txt new file mode 100644 index
> > > > 0000000..14be464
> > > > --- /dev/null
> > > > +++ b/doc/abi.txt
> > > > @@ -0,0 +1,36 @@
> > > > +ABI policy:
> > > > +	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:
> > > > +	1) At least 3 acknoweldgements of the need on the dpdk.org
> > > > +	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
> > > > +	3) The LIBABIVER variable in the makefilei(s) where the ABI changes
> > > > +are incorporated must be incremented in parallel with the ABI changes
> > > > +themselves
> > > > +
> > > > +	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.
> >
> > Hi Thomas,
> >
> > Should there be a reference to this document in the programmers guide?
> >
> Thats a good question. I think, as Thomas notes, it probably should be
> referenced in some way.  The programmers guide might be good.  What
> might be
> better would be checking the deprecation notices and adding them to the
> release
> notes for any given release.
> 
> Thoughts?

I'd suggest that the policy itself should go in, or at least be referenced from, the programmer's guide. I agree that the deprecation notices themselves should go in the release notes.

> Neil
> 
> > Regards,
> >
> > Bernard.
> >
> >

  parent reply	other threads:[~2015-01-20 14:32 UTC|newest]

Thread overview: 99+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2014-12-20 21:01 [dpdk-dev] Add DSO symbol versioning to supportbackwards compatibility Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2014-12-22 14:01   ` Gonzalez Monroy, Sergio
2014-12-22 16:22     ` Neil Horman
2014-12-22 16:34     ` Neil Horman
2014-12-22 17:09       ` Gonzalez Monroy, Sergio
2014-12-22 19:00         ` Neil Horman
2014-12-22 20:04           ` Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 3/4] Add library version extenstion Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 4/4] docs: Add ABI documentation Neil Horman
2014-12-22 20:24 ` [dpdk-dev] [PATCH v2 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2014-12-22 20:24   ` [dpdk-dev] [PATCH v2 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-12-22 20:24   ` [dpdk-dev] [PATCH v2 3/4] Add library version extenstion Neil Horman
2014-12-23 13:05     ` Gonzalez Monroy, Sergio
2014-12-23 15:50       ` Neil Horman
2014-12-22 20:24   ` [dpdk-dev] [PATCH v2 4/4] docs: Add ABI documentation Neil Horman
2014-12-23  9:48     ` Iremonger, Bernard
2014-12-23 13:01       ` Neil Horman
2014-12-23 13:27   ` [dpdk-dev] [PATCH v2 1/4] compat: Add infrastructure to support symbol versioning Gonzalez Monroy, Sergio
2014-12-23 15:50     ` Neil Horman
2014-12-23 15:51 ` [dpdk-dev] [PATCH v3 " Neil Horman
2014-12-23 15:51   ` [dpdk-dev] [PATCH v3 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-12-29 16:21     ` Sergio Gonzalez Monroy
2015-01-14 15:29     ` Thomas Monjalon
2015-01-14 16:24       ` Neil Horman
2014-12-23 15:51   ` [dpdk-dev] [PATCH v3 3/4] Add library version extenstion Neil Horman
2014-12-23 16:44     ` Gonzalez Monroy, Sergio
2014-12-23 17:08       ` Neil Horman
2014-12-29 16:23     ` Sergio Gonzalez Monroy
2015-01-14 15:48     ` Thomas Monjalon
2014-12-23 15:51   ` [dpdk-dev] [PATCH v3 4/4] docs: Add ABI documentation Neil Horman
2014-12-29 16:24     ` Sergio Gonzalez Monroy
2015-01-14 15:59     ` Thomas Monjalon
2015-01-14 20:07       ` Neil Horman
2015-01-16 13:34         ` Thomas Monjalon
2014-12-29 16:20   ` [dpdk-dev] [PATCH v3 1/4] compat: Add infrastructure to support symbol versioning Sergio Gonzalez Monroy
2015-01-14 15:25   ` Thomas Monjalon
2015-01-14 20:29     ` Neil Horman
2015-01-09 12:35 ` [dpdk-dev] Add DSO symbol versioning to supportbackwards compatibility Neil Horman
2015-01-15 19:35 ` [dpdk-dev] [PATCH v4 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-15 19:35   ` [dpdk-dev] [PATCH v4 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-15 19:35   ` [dpdk-dev] [PATCH v4 3/4] Add library version extenstion Neil Horman
2015-01-15 19:35   ` [dpdk-dev] [PATCH v4 4/4] docs: Add ABI documentation Neil Horman
2015-01-30 17:13   ` [dpdk-dev] [PATCH v4 1/4] compat: Add infrastructure to support symbol versioning Gray, Mark D
2015-01-16 15:33 ` [dpdk-dev] [PATCH v5 " Neil Horman
2015-01-16 15:33   ` [dpdk-dev] [PATCH v5 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-16 15:33   ` [dpdk-dev] [PATCH v5 3/4] Add library version extenstion Neil Horman
2015-01-16 15:33   ` [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation Neil Horman
2015-01-20  7:14     ` Thomas Monjalon
2015-01-20 10:47       ` Bruce Richardson
2015-01-20 13:37       ` Iremonger, Bernard
2015-01-20 13:46         ` Thomas Monjalon
2015-01-20 14:24         ` Neil Horman
2015-01-20 14:29           ` Butler, Siobhan A
2015-01-20 14:41             ` Neil Horman
2015-01-20 14:50               ` Butler, Siobhan A
2015-01-20 15:30                 ` Neil Horman
2015-01-20 14:32           ` O'driscoll, Tim [this message]
2015-01-20 14:00     ` Thomas Monjalon
2015-01-20 14:37       ` Neil Horman
2015-01-20 15:06         ` Thomas Monjalon
2015-01-20 15:35           ` Neil Horman
2015-01-20 21:17 ` [dpdk-dev] [PATCH v6 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-20 21:17   ` [dpdk-dev] [PATCH v6 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-20 21:17   ` [dpdk-dev] [PATCH v6 3/4] Add library version extenstion Neil Horman
2015-01-20 21:17   ` [dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation Neil Horman
2015-01-21 10:13     ` Iremonger, Bernard
2015-01-21 10:25     ` Thomas Monjalon
2015-01-21 14:59       ` Neil Horman
2015-01-21 16:05         ` Thomas Monjalon
2015-01-21 19:43           ` Neil Horman
2015-01-21 22:24             ` Thomas Monjalon
2015-01-22 19:21               ` Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 01/26] version: 2.0.0-rc0 Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 02/26] mk: fix link to static combined library Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 03/26] eal: fix check for power of 2 in 0 case Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 04/26] ethdev: fix missing parenthesis in mac check Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 05/26] mem: search only dpdk hugetlbfs maps Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 06/26] log: remove unnecessary stubs Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 07/26] vfio: avoid enabling while the module is not loaded Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 08/26] bond: fix vlan flag interpretation Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 09/26] app/testpmd: remove duplicated function for list parsing Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 10/26] nic_uio: fix thread structure compatibility for future FreeBSD Neil Horman
2015-01-21 20:58   ` [dpdk-dev] [PATCH v7 01/26] version: 2.0.0-rc0 Neil Horman
2015-01-21 20:59 ` [dpdk-dev] [PATCH v7 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-21 20:59   ` [dpdk-dev] [PATCH v7 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-21 20:59   ` [dpdk-dev] [PATCH v7 3/4] Add library version extenstion Neil Horman
2015-01-21 20:59   ` [dpdk-dev] [PATCH v7 4/4] docs: Add ABI documentation Neil Horman
2015-01-22 10:56     ` Iremonger, Bernard
2015-01-22 15:37       ` Neil Horman
2015-01-22 15:49 ` [dpdk-dev] [PATCH v8 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-22 15:49   ` [dpdk-dev] [PATCH v8 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-22 15:49   ` [dpdk-dev] [PATCH v8 3/4] Add library version extenstion Neil Horman
2015-01-22 15:49   ` [dpdk-dev] [PATCH v8 4/4] docs: Add ABI documentation Neil Horman
2015-01-22 16:46     ` Butler, Siobhan A
     [not found] ` <1422898822-16422-1-git-send-email-nhorman@tuxdriver.com>
     [not found]   ` <1422898822-16422-4-git-send-email-nhorman@tuxdriver.com>
2015-02-03 15:24     ` [dpdk-dev] [PATCH v9 " Thomas Monjalon
2015-02-03 16:01 ` [dpdk-dev] Add DSO symbol versioning to supportbackwards compatibility Thomas Monjalon
2015-02-03 20:20   ` Neil Horman

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=26FA93C7ED1EAA44AB77D62FBE1D27BA54CA6491@IRSMSX102.ger.corp.intel.com \
    --to=tim.o'driscoll@intel.com \
    --cc=bernard.iremonger@intel.com \
    --cc=dev@dpdk.org \
    --cc=nhorman@tuxdriver.com \
    /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

DPDK patches and discussions

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ https://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git