From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thomas Monjalon Subject: Re: [PATCH v6 4/4] docs: Add ABI documentation Date: Wed, 21 Jan 2015 11:25:48 +0100 Message-ID: <1771047.ADEq3JXZ2F@xps13> 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> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7Bit Cc: dev-VfR2kkLFssw@public.gmane.org To: Neil Horman Return-path: In-Reply-To: <1421788679-9433-4-git-send-email-nhorman-2XuSBdqkA4R54TAoqtyWWQ@public.gmane.org> List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces-VfR2kkLFssw@public.gmane.org Sender: "dev" 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. [...] > --- /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. > + > + 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. Other comment, what about the additions I suggested about macros and structure renaming? Neil, we expect that you consider comments done previously and that you test your patch. Otherwise, we are losing time in useless reviews. -- Thomas