[Xcb] RFC: The need to break the API. (Im)Possible?

[Josh Triplett]

On Sat, Jul 19, 2014 at 10:11:41PM +0200, Daniel Martin wrote:
> Dear list readers,
> 
> we've had a few places in proto we couldn't fix correctly as a correct
> fix would break the API of libxcb, recently. Then I see a lot of places
> in proto that should be changed to represent the actual protocol more
> precisely. To mention a few:
> - replace valueparams with switch/bitcases
> - replace unions with switch/cases (yes, they aren't supported yet)
> - or just the typo "permament":
>     http://cgit.freedesktop.org/xcb/proto/tree/src/xkb.xml#n471
> 
> I would like to contribute such changes to proto, but they all break the
> API of libxcb. So, does anyone has an idea how we can handle such
> changes?

First of all, I'm somewhat less concerned about breaking *API* than
about beaking *ABI*.  A change like s/permament/permanent/ would break
API compatibility, but would not break the library ABI, and would not
require an SONAME change.

In some cases, we could generate new API without breaking the old.  For
instance, in the case of "permament", on any platform that supports
anonymous unions, we could support both field names; for types, a
#define would preserve API compatibility.  (Perhaps add a "compat-names"
attribute?  Also, please generate a comment next to the compatibility
names saying "Backward compatibility", so people know the preferred name
when reading the definition.)

In the valueparam and union cases, what would the new API look like
compared to the old, and could we in any way preserve the old API as
well?

> PS: Replacing unions with switch/cases is one requirement if anyone ever
>     wants to generate the byte-swapping code for the server. ;)

Which I'd love to see.

- Josh Triplett