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

[Emil Velikov]

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.
+
+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
+(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.
+
+
 Libweston design goals
 ----------------------
 
-- 
2.8.2