From: Emil Velikov <emil.veli...@collabora.com> Signed-off-by: Emil Velikov <emil.veli...@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 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel