[dpdk-dev,v6,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>

---
Change notes:

v5) Updated documentation to add notes from Thomas M.

v6) Moved abi.txt to guides/rel_notes/abi.rst
---
 doc/guides/rel_notes/abi.rst | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 doc/guides/rel_notes/abi.rst
  

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> Sent: Tuesday, January 20, 2015 9:18 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH v6 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>
> 
> ---
> Change notes:
> 
> v5) Updated documentation to add notes from Thomas M.
> 
> v6) Moved abi.txt to guides/rel_notes/abi.rst
> ---
>  doc/guides/rel_notes/abi.rst | 38 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>  create mode 100644 doc/guides/rel_notes/abi.rst

Hi Neil,

The file doc/guides/rel_notes/index.rst  should be modified to include "abi" so that the abi.rst file is included in the release notes.

> 
> diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/abi.rst new file mode 100644 index
> 0000000..98ac19d
> --- /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.
> +
> +	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:

The #.  Syntax could be used for numbered lists

> +	1) At least 3 acknoweldgements of the need on the dpdk.org

A blank line is needed otherwise the text will concatenate.

> +	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

A blank line is needed otherwise the text will concatenate.

> +	3) The LIBABIVER variable in the makefilei(s) where the ABI changes
> +are incorporated must be incremented in parallel with the ABI changes
> +themselves

A blank line is needed otherwise the text will concatenate.
> +
> +	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.
> +
> +Deprecation Notices
> +===================
> +
> --
> 2.1.0
Regards,

Bernard.
  

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 <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

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.
  

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 <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
> 
> 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
>
  

2015-01-21 09:59, Neil Horman:
> 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 <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
> > 
> > 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.

I'm afraid you don't understand what I'm saying. Copy/paste:
"No, I was suggesting to explain in this doc that macro removal must be
announced with a deprecation notice,
and that in case structure must be reworked, the name must change if we
want to preserve ABI compatibility with old structure."
Rewording: if you agree with this policy, please add it in this document.

> > 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.

Now, I'm really upset of your wrong assumptions.
You sent your first proposal on september, during 1.8 cycle, not 1.7 !
And during this cycle, the decision was to postpone it for 2.0 release.

I don't understand what's wrong with you.
You don't make any effort to understand what we are saying and
you make no effort to understand what is this doc directory.
You prefer crying that your patch is not applied.
And I still don't understand if you are willing to work on a test tool for ABI?

> 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.

Note that I'm sure we can do some good work together. And I'd prefer more
pleasant discussions. Life is too short to have this kind of conflict.
  

On Wed, Jan 21, 2015 at 05:05:51PM +0100, Thomas Monjalon wrote:
> 2015-01-21 09:59, Neil Horman:
> > 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 <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
> > > 
> > > 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.
> 
> I'm afraid you don't understand what I'm saying. Copy/paste:
> "No, I was suggesting to explain in this doc that macro removal must be
> announced with a deprecation notice,
> and that in case structure must be reworked, the name must change if we
> want to preserve ABI compatibility with old structure."
> Rewording: if you agree with this policy, please add it in this document.
> 
Yes, we're on the same page regarding what your asking, I just don't agree that
it needs to be explicitly called out.  I thought I was clear on that.
Appaerntly not however, so if it will settle the point, I'll just add it.

> > > 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.
> 
> Now, I'm really upset of your wrong assumptions.
> You sent your first proposal on september, during 1.8 cycle, not 1.7 !
> And during this cycle, the decision was to postpone it for 2.0 release.
> 
you're missing the point. I apologize for not getting the release numbers right,
it should be 1.8 to 2.0 not 1.7 to 1.8 as you note, but that doesn't really
matter.  The point was 6 months.  6 months this has been sitting around.  In
that time up to this point I've gotten one review from another devloper on the
set, and you indicating that its not ready yet.  Then, the day 1.8 released, I
reposed the patch series as we agreed, and its taken almost 5 weeks before I've
gotten any feedback on it, and then its feedback that could have been given 6
months ago (you'll note this patch was initially identical to the version I
posted back in september).  I think you can understand how I find that
frustrating.

> I don't understand what's wrong with you.
The above is whats wrong with me.  The fact that I can try and try and try to
add value to this project so that I can expand its user base, and the best I've
thus far been able to receive is indifference.  At worst, the indifference is
followed by being told that the indifference is tantamount to rejection.


> You don't make any effort to understand what we are saying and
> you make no effort to understand what is this doc directory.
> You prefer crying that your patch is not applied.
No effort?  How many emails have I written contesting your opinions, presenting
supporting evidence, only to be met with assertions?  I don't think I'm the one
not making an effort here.

> And I still don't understand if you are willing to work on a test tool for ABI?
> 
From this email
http://dpdk.org/ml/archives/dev/2015-January/011306.html

=======================================================
> Yes, it should be another patchset.
> Do you plan to work on it? It would be very convenient for developpers and
> maintainers to test ABI compatibility.
> 
Gladly, if we can get this in.  I think its an important tool.
=========================================================

I'm not sure how thats unclear, but in the event that it wasn't, yes, I will
gladly work on such a tool.

> > 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.
> 
> Note that I'm sure we can do some good work together. And I'd prefer more
> pleasant discussions. Life is too short to have this kind of conflict.
> 
I agree, and we've done so in the past.  I'm sorry if I've upset you, it wasn't
my intention.  That said, can you see how I might be frustrated by this patch
set taking 6 months to get reviewed, only to have commentary made on it that I
could have handled back at the beginning of this whole mess?

Participation.  Thats really whats needed here.  Not just from you, not just
from me, everyone, and not just on the items that we consider important to
ourselves.  Indifference leads to exclusion and frustration. 


I'll have another version of this ready soon.
Neil
  

2015-01-21 14:43, Neil Horman:
> On Wed, Jan 21, 2015 at 05:05:51PM +0100, Thomas Monjalon wrote:
> > 2015-01-21 09:59, Neil Horman:
> > > 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.
> > 
> > I'm afraid you don't understand what I'm saying. Copy/paste:
> > "No, I was suggesting to explain in this doc that macro removal must be
> > announced with a deprecation notice,
> > and that in case structure must be reworked, the name must change if we
> > want to preserve ABI compatibility with old structure."
> > Rewording: if you agree with this policy, please add it in this document.
> > 
> Yes, we're on the same page regarding what your asking, I just don't agree that
> it needs to be explicitly called out.  I thought I was clear on that.
> Appaerntly not however, so if it will settle the point, I'll just add it.

OK maybe I didn't explain enough my proposal.
You can disagree but I want to be sure we think about the same thing.

1) Macros are not part of the ABI but can be part of the API.
Such macro removal must be announced in the previous release.
2) Structures are part of the ABI but cannot be versionned as the functions.
So an ABI breaking change should be done by cloning the structure in a new one.
And the API functions where this structure appears should be cloned and versionned
to support new structure while keeping old version.

Maybe that these precisions are confuse and useless.
Now I think I understand what you were saying by "an exhaustive list isn't needed".
You mean listing all types of ABI/API breakage like I did with these 2 cases, right?
I thought it was related to list of real/effective deprecations.

> > > > 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.
> > 
> > Now, I'm really upset of your wrong assumptions.
> > You sent your first proposal on september, during 1.8 cycle, not 1.7 !
> > And during this cycle, the decision was to postpone it for 2.0 release.
> > 
> you're missing the point. I apologize for not getting the release numbers right,
> it should be 1.8 to 2.0 not 1.7 to 1.8 as you note, but that doesn't really
> matter.  The point was 6 months.  6 months this has been sitting around.

No, 5 months. Yes, it's long.

> In that time up to this point I've gotten one review from another devloper on the
> set, and you indicating that its not ready yet.  Then, the day 1.8 released, I
> reposed the patch series as we agreed, and its taken almost 5 weeks before I've
> gotten any feedback on it, and then its feedback that could have been given 6
> months ago (you'll note this patch was initially identical to the version I
> posted back in september).  I think you can understand how I find that
> frustrating.

You must understand that I'd prefer more people feel involved by this change.
It would be saner to have this policy reviewed and acked by many developpers.
As it was announced on the roadmap for 2.0, this first month of the cycle was
ideal to have more discussions on how this policy can be precisely applied.
You only received my comments (which may be useless) and it's now time to
apply this important patchset.

> > I don't understand what's wrong with you.
> The above is whats wrong with me.  The fact that I can try and try and try to
> add value to this project so that I can expand its user base, and the best I've
> thus far been able to receive is indifference.  At worst, the indifference is
> followed by being told that the indifference is tantamount to rejection.
> 
> 
> > You don't make any effort to understand what we are saying and
> > you make no effort to understand what is this doc directory.
> > You prefer crying that your patch is not applied.
> No effort?  How many emails have I written contesting your opinions, presenting
> supporting evidence, only to be met with assertions?  I don't think I'm the one
> not making an effort here.

At the end, I accept your point of view and will apply the patchset.

> > And I still don't understand if you are willing to work on a test tool for ABI?
> > 
> From this email
> http://dpdk.org/ml/archives/dev/2015-January/011306.html
> 
> =======================================================
> > Yes, it should be another patchset.
> > Do you plan to work on it? It would be very convenient for developpers and
> > maintainers to test ABI compatibility.
> > 
> Gladly, if we can get this in.  I think its an important tool.
> =========================================================
> 
> I'm not sure how thats unclear, but in the event that it wasn't, yes, I will
> gladly work on such a tool.

OK thanks, it would be helpful to have it in release 2.0.

> > > 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.
> > 
> > Note that I'm sure we can do some good work together. And I'd prefer more
> > pleasant discussions. Life is too short to have this kind of conflict.
> > 
> I agree, and we've done so in the past.  I'm sorry if I've upset you, it wasn't
> my intention.  That said, can you see how I might be frustrated by this patch
> set taking 6 months to get reviewed, only to have commentary made on it that I
> could have handled back at the beginning of this whole mess?

Yes, I was hoping more people would participate in this discussion.

> Participation.  Thats really whats needed here.  Not just from you, not just
> from me, everyone, and not just on the items that we consider important to
> ourselves.  Indifference leads to exclusion and frustration.

You're totally right. Participation is the key.
Sometimes, we have to *carefully* review patches whose we have no interest.
And maybe someone else will do the same thing for a patch we care.
This is a message ;)
  

On Wed, Jan 21, 2015 at 11:24:12PM +0100, Thomas Monjalon wrote:
> 2015-01-21 14:43, Neil Horman:
> > On Wed, Jan 21, 2015 at 05:05:51PM +0100, Thomas Monjalon wrote:
> > > 2015-01-21 09:59, Neil Horman:
> > > > 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.
> > > 
> > > I'm afraid you don't understand what I'm saying. Copy/paste:
> > > "No, I was suggesting to explain in this doc that macro removal must be
> > > announced with a deprecation notice,
> > > and that in case structure must be reworked, the name must change if we
> > > want to preserve ABI compatibility with old structure."
> > > Rewording: if you agree with this policy, please add it in this document.
> > > 
> > Yes, we're on the same page regarding what your asking, I just don't agree that
> > it needs to be explicitly called out.  I thought I was clear on that.
> > Appaerntly not however, so if it will settle the point, I'll just add it.
> 
> OK maybe I didn't explain enough my proposal.
> You can disagree but I want to be sure we think about the same thing.
> 
> 1) Macros are not part of the ABI but can be part of the API.
> Such macro removal must be announced in the previous release.
> 2) Structures are part of the ABI but cannot be versionned as the functions.
> So an ABI breaking change should be done by cloning the structure in a new one.
> And the API functions where this structure appears should be cloned and versionned
> to support new structure while keeping old version.
> 
> Maybe that these precisions are confuse and useless.
> Now I think I understand what you were saying by "an exhaustive list isn't needed".
> You mean listing all types of ABI/API breakage like I did with these 2 cases, right?
> I thought it was related to list of real/effective deprecations.
> 
> > > > > 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.
> > > 
> > > Now, I'm really upset of your wrong assumptions.
> > > You sent your first proposal on september, during 1.8 cycle, not 1.7 !
> > > And during this cycle, the decision was to postpone it for 2.0 release.
> > > 
> > you're missing the point. I apologize for not getting the release numbers right,
> > it should be 1.8 to 2.0 not 1.7 to 1.8 as you note, but that doesn't really
> > matter.  The point was 6 months.  6 months this has been sitting around.
> 
> No, 5 months. Yes, it's long.
> 
> > In that time up to this point I've gotten one review from another devloper on the
> > set, and you indicating that its not ready yet.  Then, the day 1.8 released, I
> > reposed the patch series as we agreed, and its taken almost 5 weeks before I've
> > gotten any feedback on it, and then its feedback that could have been given 6
> > months ago (you'll note this patch was initially identical to the version I
> > posted back in september).  I think you can understand how I find that
> > frustrating.
> 
> You must understand that I'd prefer more people feel involved by this change.
> It would be saner to have this policy reviewed and acked by many developpers.
> As it was announced on the roadmap for 2.0, this first month of the cycle was
> ideal to have more discussions on how this policy can be precisely applied.
> You only received my comments (which may be useless) and it's now time to
> apply this important patchset.
> 
> > > I don't understand what's wrong with you.
> > The above is whats wrong with me.  The fact that I can try and try and try to
> > add value to this project so that I can expand its user base, and the best I've
> > thus far been able to receive is indifference.  At worst, the indifference is
> > followed by being told that the indifference is tantamount to rejection.
> > 
> > 
> > > You don't make any effort to understand what we are saying and
> > > you make no effort to understand what is this doc directory.
> > > You prefer crying that your patch is not applied.
> > No effort?  How many emails have I written contesting your opinions, presenting
> > supporting evidence, only to be met with assertions?  I don't think I'm the one
> > not making an effort here.
> 
> At the end, I accept your point of view and will apply the patchset.
> 
> > > And I still don't understand if you are willing to work on a test tool for ABI?
> > > 
> > From this email
> > http://dpdk.org/ml/archives/dev/2015-January/011306.html
> > 
> > =======================================================
> > > Yes, it should be another patchset.
> > > Do you plan to work on it? It would be very convenient for developpers and
> > > maintainers to test ABI compatibility.
> > > 
> > Gladly, if we can get this in.  I think its an important tool.
> > =========================================================
> > 
> > I'm not sure how thats unclear, but in the event that it wasn't, yes, I will
> > gladly work on such a tool.
> 
> OK thanks, it would be helpful to have it in release 2.0.
> 
Its not going to make 2.0, its a big undertaking.  If you wanted it in 2.0 that
would have been something to bring up 5 months ago.