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

[Emil Velikov]

On 9 July 2016 at 16:32, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> On Thu, 7 Jul 2016 20:08:40 +0200
> Quentin Glidic <sardemff7+wayland at sardemff7.net> wrote:
>
>> On 07/07/2016 18:11, Emil Velikov wrote:
>> > On 7 July 2016 at 10:05, Pekka Paalanen <ppaalanen at gmail.com> wrote:
>> >>
>>  >> [snip]
>> >>
>> >> Now that you mentioned the semantics could be of upper or lower
>> >> limit, the name should imply the meaning. I only thought of using
>> >> it as both lower limit (as in pkg-config check) *and* upper limit
>> >> (do not declare API that was added after the given version or
>> >> remove API that was deprecated after the given version).
>> >>
>> > Ack. Considering I already know how it would/should be used, I'm a bit
>> > short on unbiased name. Your earlier suggestion sounds great imho, but
>> > if you have something else in mind please share it :-)
>> >
>> >> However, I also realized something more.
>> >>
>> >> If you do like I suggested for configure.ac, you would have trouble
>> >> using pre-releases of libweston.
>> >>
>> >> Pre-releases of, say 1.13.0, will be released as 1.12.9x. That
>> >> would be MINOR=12, so if you use the same numbers for both
>> >> pkg-config check and for the CPP macro for API, you cannot test the
>> >> 13 API until it has been finally released.
>> >>
>> >> So maybe those two need to be separate anyway?
>> >>
>> > The example will cover this confusion, but the gist is that:
>> >  - No released version of software X should rely on development
>> > version of libweston/libfoo.
>
> Hi Emil,
>
> an unreleased project must be able to depend on unreleased
> libweston.
>
> That's how the project communicates to its testers and developers
> explicitly in configure.ac that it needs an unreleased version of
> libweston. And we need projects to be able to do that, so that we
> can have people test unreleased APIs of libweston.
>
> This is what we currently do with 1.y.90 version. We never release
> a 1.y.90, but projects can still check for and require it. It's
> been working fine between wayland and weston so far, AFAIK.
>
> Version 1.y.90 is not a proper version, it does not tell you which
> revision of the code is the right one, but it does say "WIP" which
> IMO is an important message.
>
> If the user project then gets released with a dependency to a
> library version 1.y.90, that's their fault. Hopefully they kept up
> to date, so that release 1.y.91 satisfies the dependency.
>
Fully agree.

Speaking of which... I don't think we got the wayland patch for mesa
in. /me double-checks.

>> >  - If there's a serious need to void the above, one should set the
>> > REQUIRED_API to the number it would be in an official/final version.
>
> Indeed.
>
> This is why my desire to derive both pkg-config version check and
> the REQUIRED_API define from the single same source variable does
> not work after all.
>
> So, I think you're right, and we agree.
>
>> >
>> > Example:
>> > libweston (devel. process):
>> > - git tag 1.12.90
>> > - Add API X, guarded behind version 0x010d version check (one could
>> > keep the numbers decimal and/or other)
>> > - other...
>> >
>> > User:
>> > - Bump required version to 1.12.90
>> > - Use "-DREQUIRED_API_VERSION=0x010d"
>> > Personally I'm leaning towards adding the define only in the
>> > respective places that need the newer API, but having it in configure
>> > (global scale) would be nice as well.
>>
>> Regarding that, I’d go the GLib/GTK+ way completely.
>> That means each function has a
>> WESTON_AVAILABLE_IN(1, 13)
>>
>> and *if* a project set
>> WESTON_VERSION_{MIN,MAX}_ALLOWED, that will make these functions
>> deprecated (not sure for the ones above the MAX).
>>
>> The maint point is that I would rather have the new functions without
>> needing to update the define. Or most projects will use 0xffff as the
>> value. :-)
>
> Hi Quentin,
>
> I would not have new functions exposed without updating the define
> value in user projects. Why? It gives the libweston users *both*
> options.
>
> I don't consider using 0xffff as a hack. I see it as an opt-in to
> the scheme you are proposing, to get new functions exposed
> automatically, which also puts you at risk of accidentally
> depending on a newer version of libweston than before.
>
> If we expose new functions regardless the define, then no-one can
> choose to be safe from that accident, even if they wanted to.
>
> Oh, reading your later replies, it seems you are only arguing over
> which policy should be the default. I'd say neither. Make the build
> just error out if the user defines neither way. The definition will
> be just one line in the user project's config.h anyway.
>
>
You're right - calling 0xffff names isn't the most mature thing, sorry
about that.

And yes, the goal here is/was to error out by default in order to
avoid accidental damage. Anyone not interested in this safety switch
can add one line to override it.

Thanks for guidance in all this.
Emil