[libvirt] [PATCH] RFC: maint: Sort public symbols within a release

[Daniel P. Berrangé]

On Fri, Jun 21, 2019 at 02:18:23PM -0500, Eric Blake wrote:
> In libvirt_private.syms, we have a policy of keeping blocks of symbols
> sorted by name - in fact, we enforce it during 'make check' with our
> check-symsorting rule calling out to a perl script.  But
> libvirt_public.syms has been more cavalier over the years.
> 
> 21 releases have been trivially sorted due to adding only one symbol;
> while the following 27 releases listed multiple symbols in
> alphabetical order, even if the symbols were not chronologically added
> in that order [1]:
> 
> 0.0.3   0.9.5   1.1.0
> 0.3.0   0.9.7   1.1.1
> 0.3.3   0.9.8   1.2.5
> 0.4.2   0.9.9   1.2.8
> 0.6.3   0.9.10  1.2.11
> 0.7.5   0.9.13  1.2.15
> 0.9.0   1.0.1   1.3.3
> 0.9.2   1.0.2   3.1.0
> 0.9.3   1.0.3   3.4.0
> 
> [1] Case study: git log -p v0.9.9..v0.9.10 src/libvirt_public.syms
> shows 9 commits adding 9 APIs among 7 authors:
> 0b7ddf9e - trivially in order
> adb99a05 - appending happened to also be sorted order
> 1f7aa0ac - irrelevant (removing TABs, not adding symbol)
> 6714fd04 - added in sorted order
> 8f8b0802 - appended, out of order
> e1eea747 - re-sorted previous addition, and added in sorted order
> 02af3e13 - added in sorted order
> c471e55e - added in sorted order
> 99fd69c3 - added in sorted order
> 
> The following patch changes the remaining 37 releases to do likewise,
> and documents the practice.
> 
> Signed-off-by: Eric Blake <eblake at redhat.com>
> 
> ---
> 
> I'm not sure if we want this patch - it got much bigger than I was
> expecting. 37 releases is less than half of the total versions in the
> file, but larger than the number of releases that were sorted (where
> it is not even obvious if that was always intentional or by luck).  We
> could also decide to adopt a policy of listing symbols in the same
> order as remote_protocol.x (although not all symbols go over RPC), but
> that seems like it would be even more churn and harder to enforce.
> 
> Ideally, if we DO want this patch, we should also teach 'make check'
> via src/check-symsorting.pl how to enforce it on the public file; as I
> did not do that, this is marked RFC.

I've no objection to sorting the public sym file.

If we do this though, I'd consider check-symsorting.pl to be a must
have. Too much liklihood of regression if we rely on reviewers
catching it.


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|