From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 50AAB5A15 for ; Wed, 21 Jan 2015 15:59:15 +0100 (CET) Received: from nat-pool-rdu-t.redhat.com ([66.187.233.202] helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1YDwkN-0002gn-2W; Wed, 21 Jan 2015 09:59:12 -0500 Date: Wed, 21 Jan 2015 09:59:01 -0500 From: Neil Horman To: Thomas Monjalon Message-ID: <20150121145901.GA18943@localhost.localdomain> 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> <1771047.ADEq3JXZ2F@xps13> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1771047.ADEq3JXZ2F@xps13> User-Agent: Mutt/1.5.23 (2014-03-12) X-Spam-Score: -2.9 (--) X-Spam-Status: No Cc: 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 21 Jan 2015 14:59:15 -0000 On Wed, Jan 21, 2015 at 11:25:48AM +0100, Thomas Monjalon wrote: > 2015-01-20 16:17, 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. > > > > v6) Moved abi.txt to guides/rel_notes/abi.rst > > You didn't integrate this file in the index. > Shiobahn indicated that its just a plain text file, so I left it as a plain text file. I guess we have different definitions of plain text files. > [...] > > > --- /dev/null > > +++ b/doc/guides/rel_notes/abi.rst > > @@ -0,0 +1,38 @@ > > +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. > > As previously said, speaking about 2.0/2.1 would be more coherent. > As previously mentioned, I really don't see this as relevant, as it will be out of date within a release, and I think we can agree, no one is going to update this paragraph every release. > > + > > + 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. > > When applying the patch, there are these (minor) warnings: > > /home/thomas/projects/dpdk/dpdk/.git/rebase-apply/patch:52: trailing whitespace. > /home/thomas/projects/dpdk/dpdk/.git/rebase-apply/patch:55: new blank line at EOF. > > When building the documentation, there are these errors: > make doc-guides-html > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:4: WARNING: Block quote ends without a blank line; unexpected unindent. > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:8: WARNING: Block quote ends without a blank line; unexpected unindent. > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:15: WARNING: Block quote ends without a blank line; unexpected unindent. > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:18: WARNING: Block quote ends without a blank line; unexpected unindent. > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:20: ERROR: Unexpected indentation. > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:22: WARNING: Block quote ends without a blank line; unexpected unindent. > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:25: ERROR: Unexpected indentation. > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:26: WARNING: Block quote ends without a blank line; unexpected unindent. > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:29: WARNING: Block quote ends without a blank line; unexpected unindent. > /home/thomas/projects/dpdk/dpdk/doc/guides/rel_notes/abi.rst:: WARNING: document isn't included in any toctree > > Please check it. > Again, I guess we have separate definitions of what a plain text file is, but I'll look into it. > Other comment, what about the additions I suggested about macros and structure renaming? > Considered and answered already. I'm in favor of listing macros and structure changes in the abi document, but I think an exhaustive list isn't needed. If it is, we could spend pages diving into minute. Better to point out the need for abi noticies as patches get posted. > Neil, we expect that you consider comments done previously and that you test your patch. > Otherwise, we are losing time in useless reviews. > Thomas, I have considered your comments, I simply don't agree with all of them, and I made that clear. As for losing time, you let the first attempt at this patch rot on the list in 1.7 and have done the same thing for the 1.8 cycle until I yelled for reviews. No doubt when all is said and done here you'll complain because this series likely won't work when you apply it for all the patches you take between the time I posted it and now. So lets be careful about complaining over wasted time. Neil > -- > Thomas >