[PATCH weston v2 2/4] README: updates on libweston versioning

Mon Aug 15 13:53:51 UTC 2016

On Mon, Aug 15, 2016 at 03:16:48PM +0300, Pekka Paalanen wrote:
> From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> 
> 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 <pekka.paalanen at collabora.co.uk>

Reviewed-by: Jonas Ådahl <jadahl at gmail.com>

> ---
>  README | 51 ++++++++++++++++++++++++++++++++++++---------------
>  1 file changed, 36 insertions(+), 15 deletions(-)
> 
> diff --git a/README b/README
> index 37090d5..91a4953 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
>  ---------------------
> -- 
> 2.7.3
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel