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

[Quentin Glidic]

On 22/07/2016 15:51, Emil Velikov wrote:
> From: Emil Velikov <emil.velikov at collabora.com>
>
> Signed-off-by: Emil Velikov <emil.velikov at collabora.com>
> ---
> Pekka, considering the noticable rework I've dropped your r-b.
>
> v2:
>  - s/QT/Qt/;s/GTK/GDK/
>  - s/LIBWESTON_API_VERSION/REQUIRE_LIBWESTON_API_VERSION/
>  - Provide configure.ac example and mention how to override the fwd
> compat checking.
>  - Misc rewording and improvements.
> ---
>  README | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 49 insertions(+)
>
> diff --git a/README b/README
> index 0ebe06e..37090d5 100644
> --- a/README
> +++ b/README
> @@ -70,6 +70,55 @@ 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.
> +
> +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
> +---------------------
> +
> +Inspired by ATK, Qt and KDE programs/libraries, libjpeg-turbo, GDK,
> +NetworkManager, js17, lz4 and many others, libweston uses a macro to restrict
> +the API visible to the developer - REQUIRE_LIBWESTON_API_VERSION.
> +
> +Note that different projects focus on different aspects - upper and/or lower
> +version check, default to visible/hidden old/new symbols and so on.
> +
> +libweston aims to guard all newly introduced API, in order to prevent subtle
> +breaks that a simple recompile (against a newer version) might cause.
> +
> +The macro is of the format 0x$MAJOR$MINOR and does not include PATCH version.

Nit below on that.


> +As mentioned in the Versioning scheme section, the latter does not reflect any
> +user visible API changes, thus should be not considered part of the API version.
> +
> +All new symbols should be guarded by the macro like the example given below:
> +
> +#if REQUIRE_LIBWESTON_API_VERSION >= 0x0101
> +

Nit: Shouldn’t we provide a macro to generate this number? It’s not just 
concatenation of $MAJOR $MINOR, so people would read 
LIBWESTON_ENCODE_VERSION(10, 20) more easily than (0x0a14).

Except for that nice-to-have convenience macro “missing”:
Reviewed-by: Quentin Glidic <sardemff7+git at sardemff7.net>

Cheers,


> +bool
> +weston_ham_sandwich(void);
> +
> +#endif
> +
> +In order to use the said symbol, the one will have a similar code in their
> +configure.ac:
> +
> +PKG_CHECK_MODULES(LIBWAYLAND, [libwayland-1 >= 1.1])
> +AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [0x0101])
> +
> +If the user is _not_ interested in forward compatibility, they can use 0xffff
> +or similar high value. Yet doing so is not recommended.
> +
> +
>  Libweston design goals
>  ----------------------
>
>


-- 

Quentin “Sardem FF7” Glidic