[PATCH weston 3/6] README: Document versioning scheme, forward compatibility

[Pekka Paalanen]

On Mon,  4 Jul 2016 15:23:51 +0100
Emil Velikov <emil.l.velikov at gmail.com> wrote:

> From: Emil Velikov <emil.velikov at collabora.com>
> 
> Signed-off-by: Emil Velikov <emil.velikov at collabora.com>
> ---
> Pekka,
> 
> There's a couple of things to 'break' - forward and backward
> compatibility.
> 
> Latter implies changing (removing) certain existing API, while the
> former is used in reference to functionality introduced with minor
> bumps.
> 
> Since people don't always know when the new API is introduced, let alone
> bump the version accordingly in configure (and thus package runtime
> dependency), things end up badly.
> 
> In some subtle cases (the autogenerated headers in wayland) not only is
> the new API available, but you end up using it without knowing. And yes,
> I fully agree that approach used in wayland is good, but it can cause
> subtle breakage.
> 
> If weston devs don't want this approach (i.e. adding the ifdef guards
> prove too annoying and/or other), then one can just stick with only with
> MAJOR. Then the number will ramp quite fast and user will have no way
> of knowing/detecting bugfix (patch versions).
> 
> From my experience, using the LIBWESTON_API_VERSION alike macros does
> not get in the way of development. Yet it's up-to you guys to make the
> call.
> 
> -Emil
> ---
>  README | 46 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 46 insertions(+)
> 
> diff --git a/README b/README
> index 126df4d..72e8c7c 100644
> --- a/README
> +++ b/README
> @@ -70,6 +70,52 @@ For more information about parallel installability, see
>  http://ometer.com/parallel.html
>  
>  
> +Versioning scheme
> +-----------------
> +
> +In order to provide consistent, easy to use versioning, libweston
> +follows the rules in the Apache Portable Runtime Project
> +http://apr.apache.org/versioning.html.

Hi Emil,

I read that doc, and I fully agree with it now.

> +
> +The document provides the full details, with the gist summed below:
> + - Major - backward incompatible changes.
> + - Minor - new backward compatible features.
> + - Patch - internal (implementation specific) fixes.
> +
> +
> +Forward compatibility
> +---------------------
> +
> +In order to ensure prevent subtle breaks with a simple recompile

Strike "ensure" perhaps?

> +(against a newer version), features introduced with minor versions are
> +guarded with a LIBWESTON_API_VERSION guard.
> +
> +For example:
> +Libweston v1.1.0 introduces a new entry point weston_ham_sandwich().
> +As such it will be annotated as below in the relevant header(s).
> +
> +#if LIBWESTON_API_VERSION >= 0x0101
> +
> +bool
> +weston_ham_sandwich(void);
> +
> +#endif
> +
> +As the user requires the said symbol, they must explicitly set the
> +LIBWESTON_API_VERSION macro. By doing so they explicitly state "yes I
> +want to use the said version of the library", at which point they should
> +also bump the version check in their configure (or equivalent) script.
> +
> +The LIBWESTON_API_VERSION is of the format 0x$MAJOR$MINOR and does not
> +include PATCH version. As mentioned in the Versioning scheme section,
> +PATCH does not reflect any user visible API changes, thus should be not
> +considered part of the API VERSION.
> +
> +Similar approach is used by ATK, QT and KDE programs/libraries,
> +libjpeg-turbo, GTK, NetworkManager (in a more complex/compherensive
> +manner), js17, lz4 and many others.

This is interesting and the very first time I hear about such a scheme.
Obviously I have never used any library that required me to declare
which version I am expecting to use of it at the CPP level.

Also the APR versioning doc says nothing about it, and I couldn't find
any GTK documentation of a similar mechanism. libjpeg-turbo seems to
have something of the sort indeed, however it also defines
JPEG_LIB_VERSION itself, not the user of the library. I suspect there
is some misunderstanding here. I didn't check the others.

We might need this kind of scheme for deprecating things in libwayland,
too.

So, let's see how it works for libweston. I'm in favour of this.

I think we should also have an example for how do this in a
configure.ac nicely, so that you define the version you want to use
just once, and from that it computes:
- which libweston-$N.pc to use, and the version check with it for
  pkg-config
- the generation of #define LIBWESTON_API_VERSION into config.h

Btw. is it usual for the *users* to define LIBWESTON_API_VERSION? To me
it sounds like something libweston would define. Users might define
something like REQUIRE_LIBWESTON_API_VERSION, no?

> +
> +
>  Libweston design goals
>  ----------------------
>  

The one typo(?) and the bikeshedding about the name aside:
Reviewed-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20160705/4f45949b/attachment.sig>