[dpdk-dev,v7,4/4] docs: Add ABI documentation

Message ID 1421873986-21912-4-git-send-email-nhorman@tuxdriver.com (mailing list archive)
State Superseded, archived
Headers

Commit Message

Neil Horman Jan. 21, 2015, 8:59 p.m. UTC
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.

v6) Moved abi.txt to guides/rel_notes/abi.rst

v7) Updated abi.rst to integrate with index file
    Updated abi.rst to conform to rst formatting
    Updated abi.rst to include example deprecation notices.  Its not exactly the
language that Thomas indicated, but I think it makes the idea clear.
---
 doc/guides/rel_notes/abi.rst | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 doc/guides/rel_notes/abi.rst
  

Comments

Iremonger, Bernard Jan. 22, 2015, 10:56 a.m. UTC | #1
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> Sent: Wednesday, January 21, 2015 9:00 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH v7 4/4] docs: Add ABI documentation
> 
> 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>

Hi Neil,

Tried to apply the patch and build it, the following warnings occurred.

Applying: docs: Add ABI documentation
/nfs/sie/disks/git_workspace/bairemon/dpdk-doc-next/.git/rebase-apply/patch:55: trailing whitespace.
-------------------------------  
/nfs/sie/disks/git_workspace/bairemon/dpdk-doc-next/.git/rebase-apply/patch:22: new blank line at EOF.
+
warning: 2 lines add whitespace errors.

sivswdev01> make doc-guides-html
sphinx for guides...
/nfs/sie/disks/git_workspace/bairemon/dpdk-doc-next/doc/guides/rel_notes/abi.rst:: WARNING: document isn't included in any toctree

Change to doc/guides/rel_notes/index.rst is missing from the patch.

Suggest applying and building the patch and then checking the generated HTML in Firefox to see that it is as you expect.
file:///home/nhorman/dpdk-doc-next/build/doc/html/guides/rel_notes/index.html

Regards,

Bernard.

 
> 
> ---
> Change notes:
> 
> v5) Updated documentation to add notes from Thomas M.
> 
> v6) Moved abi.txt to guides/rel_notes/abi.rst
> 
> v7) Updated abi.rst to integrate with index file
>     Updated abi.rst to conform to rst formatting
>     Updated abi.rst to include example deprecation notices.  Its not exactly the language that Thomas
> indicated, but I think it makes the idea clear.
> ---
>  doc/guides/rel_notes/abi.rst | 41 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 41 insertions(+)
>  create mode 100644 doc/guides/rel_notes/abi.rst
> 
> diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/abi.rst new file mode 100644 index
> 0000000..9b72719
> --- /dev/null
> +++ b/doc/guides/rel_notes/abi.rst
> @@ -0,0 +1,41 @@
> +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:
> +
> +#. At least 3 acknoweldgements of the need on the dpdk.org #. 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 #. 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.
> +
> +Examples of Deprecation notices
> +-------------------------------
> +* The Macro #RTE_FOO is deprecated and will be removed with version
> +2.0, to be replaced with the inline function rte_bar()
> +* The function rte_mbuf_grok has been updated to include new parameter
> +in version 2.0.  Backwards compatibility will be maintained for this
> +function until the release of version 2.1
> +* The members struct foo have been reorganized in release 2.0.  Existing binary applications will have
> backwards compatibility in release 2.0, while newly built binaries will need to reference new structure
> variant struct foo2.  Compatibility will be removed in release 2.2, and all applications will require
> updating a rebuilding to the new structure at that time, which will be renamed to the origional struct
> foo.
> +* Significant ABI changes are planned for the librte_dostuff library.  The upcomming release 2.0 will
> not contain these changes, but release 2.1 will, and no backwards compatibility is planned due to the
> invasive nature of these changes.  Binaries using this library built prior to version 2.1 will require
> updating and recompilation.
> +
> +Deprecation Notices
> +-------------------
> +
> --
> 2.1.0
  
Neil Horman Jan. 22, 2015, 3:37 p.m. UTC | #2
On Thu, Jan 22, 2015 at 10:56:08AM +0000, Iremonger, Bernard wrote:
> 
> 
> > -----Original Message-----
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> > Sent: Wednesday, January 21, 2015 9:00 PM
> > To: dev@dpdk.org
> > Subject: [dpdk-dev] [PATCH v7 4/4] docs: Add ABI documentation
> > 
> > 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>
> 
> Hi Neil,
> 
> Tried to apply the patch and build it, the following warnings occurred.
> 
> Applying: docs: Add ABI documentation
> /nfs/sie/disks/git_workspace/bairemon/dpdk-doc-next/.git/rebase-apply/patch:55: trailing whitespace.
> -------------------------------  
> /nfs/sie/disks/git_workspace/bairemon/dpdk-doc-next/.git/rebase-apply/patch:22: new blank line at EOF.
> +
> warning: 2 lines add whitespace errors.
> 
Those errors don't make much sense.  Theres no whitespace on line 55 of the
patch after the last character and line 22 isn't the end of a file that I can
see.

> sivswdev01> make doc-guides-html
> sphinx for guides...
> /nfs/sie/disks/git_workspace/bairemon/dpdk-doc-next/doc/guides/rel_notes/abi.rst:: WARNING: document isn't included in any toctree
> 
> Change to doc/guides/rel_notes/index.rst is missing from the patch.
> 
> Suggest applying and building the patch and then checking the generated HTML in Firefox to see that it is as you expect.
> file:///home/nhorman/dpdk-doc-next/build/doc/html/guides/rel_notes/index.html
> 
No, the generated html works fine.  I have the abi line added to index.rst but
somehow it didn't get comitted, so my testing worked, but the patch isn't right.
I'll resend it, and try to figure out whats wrong with those lines, though they
really seem screwy to me.
Neil

> Regards,
> 
> Bernard.
> 
>  
> > 
> > ---
> > Change notes:
> > 
> > v5) Updated documentation to add notes from Thomas M.
> > 
> > v6) Moved abi.txt to guides/rel_notes/abi.rst
> > 
> > v7) Updated abi.rst to integrate with index file
> >     Updated abi.rst to conform to rst formatting
> >     Updated abi.rst to include example deprecation notices.  Its not exactly the language that Thomas
> > indicated, but I think it makes the idea clear.
> > ---
> >  doc/guides/rel_notes/abi.rst | 41 +++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 41 insertions(+)
> >  create mode 100644 doc/guides/rel_notes/abi.rst
> > 
> > diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/abi.rst new file mode 100644 index
> > 0000000..9b72719
> > --- /dev/null
> > +++ b/doc/guides/rel_notes/abi.rst
> > @@ -0,0 +1,41 @@
> > +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:
> > +
> > +#. At least 3 acknoweldgements of the need on the dpdk.org #. 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 #. 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.
> > +
> > +Examples of Deprecation notices
> > +-------------------------------
> > +* The Macro #RTE_FOO is deprecated and will be removed with version
> > +2.0, to be replaced with the inline function rte_bar()
> > +* The function rte_mbuf_grok has been updated to include new parameter
> > +in version 2.0.  Backwards compatibility will be maintained for this
> > +function until the release of version 2.1
> > +* The members struct foo have been reorganized in release 2.0.  Existing binary applications will have
> > backwards compatibility in release 2.0, while newly built binaries will need to reference new structure
> > variant struct foo2.  Compatibility will be removed in release 2.2, and all applications will require
> > updating a rebuilding to the new structure at that time, which will be renamed to the origional struct
> > foo.
> > +* Significant ABI changes are planned for the librte_dostuff library.  The upcomming release 2.0 will
> > not contain these changes, but release 2.1 will, and no backwards compatibility is planned due to the
> > invasive nature of these changes.  Binaries using this library built prior to version 2.1 will require
> > updating and recompilation.
> > +
> > +Deprecation Notices
> > +-------------------
> > +
> > --
> > 2.1.0
> 
>
  

Patch

diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/abi.rst
new file mode 100644
index 0000000..9b72719
--- /dev/null
+++ b/doc/guides/rel_notes/abi.rst
@@ -0,0 +1,41 @@ 
+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:
+
+#. At least 3 acknoweldgements of the need on the dpdk.org
+#. 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
+#. 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.
+
+Examples of Deprecation notices
+-------------------------------  
+* The Macro #RTE_FOO is deprecated and will be removed with version 2.0, to be replaced with the inline function rte_bar()
+* The function rte_mbuf_grok has been updated to include new parameter in version 2.0.  Backwards compatibility will be maintained for this function until the release of version 2.1
+* The members struct foo have been reorganized in release 2.0.  Existing binary applications will have backwards compatibility in release 2.0, while newly built binaries will need to reference new structure variant struct foo2.  Compatibility will be removed in release 2.2, and all applications will require updating a rebuilding to the new structure at that time, which will be renamed to the origional struct foo.
+* Significant ABI changes are planned for the librte_dostuff library.  The upcomming release 2.0 will not contain these changes, but release 2.1 will, and no backwards compatibility is planned due to the invasive nature of these changes.  Binaries using this library built prior to version 2.1 will require updating and recompilation.
+
+Deprecation Notices
+-------------------
+