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

Emil Velikov emil.l.velikov at gmail.com
Fri Jul 22 13:51:50 UTC 2016

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/
 - 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.
+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:
+In order to use the said symbol, the one will have a similar code in their
+PKG_CHECK_MODULES(LIBWAYLAND, [libwayland-1 >= 1.1])
+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

More information about the wayland-devel mailing list