From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wi0-f181.google.com (mail-wi0-f181.google.com [209.85.212.181]) by dpdk.org (Postfix) with ESMTP id C6FA65A70 for ; Tue, 20 Jan 2015 09:01:54 +0100 (CET) Received: by mail-wi0-f181.google.com with SMTP id fb4so8696589wid.2 for ; Tue, 20 Jan 2015 00:01:54 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:organization :user-agent:in-reply-to:references:mime-version :content-transfer-encoding:content-type; bh=z3iextenmK768vpFh2nhEqyiSVp9PfXxNZJF+zO6PTE=; b=MlITnCg7LRMHj/NHSbyEYxEuatcZBGcTNDHhvFC60VeRcwo1ZvRVh7V1BHEhcaO7dy XDD1Qhwb8UAfpwqmxesqMTzoF7k7sPXKVFhf8y+2CGyA5kCN3vv8PJPpozJtQMiY7Hbg KIufpZ8dJ8MMtyIQTjbBs66K23V2IaMo1+82vKh6w3xqqXv5+5xxTUv7DVUdMxvrFArC aAZrnGKmRanlQYU7rXCR+MAorzD3/6dniaU6CFzZz3H/UCRn5Afml0YHhkd6MDJRrGLd DdDloV0jQCsRzZW4RYYMVJRk86e5Yb7yDrvv+KbyaUUkVj1V2EsC0hujyeJp12aOK9SX ML8A== X-Gm-Message-State: ALoCoQl13H522aFe8Ht1uQbMpoWErGkf8SQQa6sDyn50kRKs1mrm8jA4rjPgsUwJxGCXDf6p2bFq X-Received: by 10.180.212.113 with SMTP id nj17mr43833279wic.77.1421740914692; Tue, 20 Jan 2015 00:01:54 -0800 (PST) Received: from xps13.localnet (111.26.90.92.rev.sfr.net. [92.90.26.111]) by mx.google.com with ESMTPSA id 18sm20171722wjr.46.2015.01.20.00.01.52 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 20 Jan 2015 00:01:53 -0800 (PST) From: Thomas Monjalon To: Neil Horman Date: Tue, 20 Jan 2015 08:14:50 +0100 Message-ID: <27877815.OT7ntq4yug@xps13> Organization: 6WIND User-Agent: KMail/4.14.3 (Linux/3.17.6-1-ARCH; KDE/4.14.3; x86_64; ; ) In-Reply-To: <1421422389-5473-4-git-send-email-nhorman@tuxdriver.com> References: <1419109299-9603-1-git-send-email-nhorman@tuxdriver.com> <1421422389-5473-1-git-send-email-nhorman@tuxdriver.com> <1421422389-5473-4-git-send-email-nhorman@tuxdriver.com> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Cc: dev@dpdk.org Subject: Re: [dpdk-dev] [PATCH v5 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 20 Jan 2015 08:01:55 -0000 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 > CC: Thomas Monjalon > CC: "Richardson, Bruce" > > --- > 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.