From 72416979cbd5864915f9bc0116ac1a512bcb1173 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Wed, 10 Aug 2016 14:54:08 +0300 Subject: [PATCH] README: updates on libweston versioning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We have agreed to use the major as the ABI-version, so talk about major to avoid confusion. Remove unncessary or incorrect wording related to breaking ABI on minor bumps. Explain a little about the weston vs. libweston version numbers. v2: - Add a paragraph about ABI breaks between alpha and .0 releases. - clarify pre-release definition - Add two paragraphs about libweston versions differing from weston version and how to use pkg-config properly. Signed-off-by: Pekka Paalanen Reviewed-by: Quentin Glidic Reviewed-by: Jonas Ådahl Reviewed-by: Emil Velikov --- README | 51 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 36 insertions(+), 15 deletions(-) diff --git a/README b/README index 37090d59..91a49537 100644 --- a/README +++ b/README @@ -36,7 +36,7 @@ input and output systems, so that people who just want to write a new "Wayland window manager" (WM) or a small desktop environment (DE) can focus on the WM part. -Libweston was first introduced in Weston 1.9, and is expected to +Libweston was first introduced in Weston 1.12, and is expected to continue evolving through many Weston releases before it achieves a stable API and feature completeness. @@ -45,23 +45,24 @@ API/ABI (in)stability and parallel installability ------------------------------------------------- As libweston's API surface is huge, it is impossible to get it right -in one go. Therefore developers reserve the right to break the API/ABI -between every 1.x.0 Weston release (minor version bumps), just like -Weston's plugin API does. For git snapshots of the master branch, the -API/ABI can break any time without warning or version bump. +in one go. Therefore developers reserve the right to break the API/ABI and bump +the major version to signify that. For git snapshots of the master branch, the +API/ABI can break any time without warning. -Libweston API or ABI will not be broken between Weston's stable -releases 1.x.0 and 1.x.y, where y < 90. +Libweston major can be bumped only once during a development cycle. This should +happen on the first patch that breaks the API or ABI. Further breaks before the +next Weston major.0.0 release do not cause a bump. This means that libweston +API and ABI are allowed to break also after an alpha release, up to the final +release. However, breaks after alpha should be judged by the usual practices +for allowing minor features, fixes only, or critical fixes only. To make things tolerable for libweston users despite API/ABI breakages, -libweston is designed to be perfectly parallel-installable. An -API/ABI-version is defined for libweston, and it is bumped for releases as -needed. Different non-backward compatible ABI versions of libweston can be -installed in parallel, so that external projects can easily depend on a -particular ABI-version. Thus they do not have to fight over which ABI-version -is installed in a user's system. This allows a user to install many -different compositors each requiring a different libweston ABI-version -without tricks or conflicts. +different libweston major versions are designed to be perfectly +parallel-installable. This way external projects can easily depend on a +particular API/ABI-version. Thus they do not have to fight over which +ABI-version is installed in a user's system. This allows a user to install many +different compositors each requiring a different libweston ABI-version without +tricks or conflicts. Note, that versions of Weston itself will not be parallel-installable, only libweston is. @@ -82,6 +83,26 @@ The document provides the full details, with the gist summed below: - Minor - new backward compatible features. - Patch - internal (implementation specific) fixes. +Weston and libweston have separate version numbers in configure.ac. All +releases are made by the Weston version number. Libweston version number +matches the Weston version number in all releases except maybe pre-releases. +Pre-releases have the Weston micro version 91 or greater. + +A pre-release is allowed to install a libweston version greater than the Weston +version in case libweston major was bumped. In that case, the libweston version +must be Weston major + 1 and with minor and patch versions zero. + +Pkg-config files are named after libweston major, but carry the Weston version +number. This means that Weston pre-release 2.1.91 may install libweston-3.pc +for the future libweston 3.0.0, but the .pc file says the version is still +2.1.91. When a libweston user wants to depend on the fully stable API and ABI +of a libweston major, he should use (e.g. for major 3): + + PKG_CHECK_MODULES(LIBWESTON, [libweston-3 >= 3.0.0]) + +Depending only on libweston-3 without a specific version number still allows +pre-releases which might have different API or ABI. + Forward compatibility ---------------------