[PATCH weston v3 1/3] README: Document versioning scheme, forward compatibility
sardemff7+wayland at sardemff7.net
Tue Aug 2 08:52:52 UTC 2016
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.
> - 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
> +Versioning scheme
> +In order to provide consistent, easy to use versioning, libweston
> +follows the rules in the Apache Portable Runtime Project
> +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>
> +In order to use the said symbol, the one will have a similar code in their
> +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
More information about the wayland-devel