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

[Emil Velikov]

On 8 July 2016 at 12:00, Quentin Glidic <sardemff7+wayland at sardemff7.net> wrote:
> On 08/07/2016 12:52, Emil Velikov wrote:
>>
>> On 7 July 2016 at 19:08, 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.
>>>>  - 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.
>>>>
>>>> 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).
>>>
>> IMHO forward compatibility is a more important topic than deprecation.
>> Thus I've focused on it in order to only make minimal changes. Your
>> suggestions sounds like the definition of 'complex' from IRC the other
>> day, but if you want the deprecation mechanism please go ahead.
>>
>>> The maint point is that I would rather have the new functions without
>>> needing to update the define.
>>
>> That completely defeats the purpose of the whole series.
>>
>>> Or most projects will use 0xffff as the value.
>>
>> s/most/most of my/ perhaps ?  ;-)
>>
>> Bus seriously, as you noticed before - there is _nothing_ stopping
>> people from doing extremely stupid things.
>> If they do - it's up-to them to pick the pieces.
>>
>> From my limited encounter so far on the wayland ML, it seems that
>> 'compromise' it's conjugated too often :-(
>
>
> No, that series is still useful. *If* a project wants to be fully compatible
> with version x.y, it will define WESTON_MAX_ALLOWED(x, y), then newer
> symbols will be hidden.
>
> If you believe most projects will do that, then fine, they want to be
> “safe”, they do so, and they are happy.
>
> Meanwhile, I and others who do not care about complete stability (and more
> about features) can just use new symbols as they appear.
>
The above sounds quite selfish - just because you don't care that
doesn't mean you have to enforce your preference onto everyone.
Also as you pointed out yourself - one can 'shoot themselves in the
foot' by using 0xffff as MAX if they really want to.

> You said it, nothing will prevent all breakages, so why make it difficult
> for the simple case? Simple case being “just use latest version” (rolling
> releases distributions).
>
Not everyone is using rolling release distors. I would welcome you to
take a look how others are doing things and then you'll quickly
realise why I'm suggesting all this. One could say say/argue that
those distros should update (fix?) their tools, but even if they do
that's not going to happen overnight.

Ftr the "simple case" reference if one line for the whole project
isn't simple enough, I'm not sure what is.

>
> Deprecation is just the other half of the work, for people wanting to avoid
> to-be-deleted stuff.
>
The alternative doesn't sound that bad imho - just get things to
error, once the API is gone (and thus major is bumped)

>
> I would define MIN, not MAX, because I think (my) software should just go
> forward.
>

As said earlier, if you want the MIN/MAX feel free to send patches.

If you/others feel strongly against the patches in their form (with
Tiago and pq's comments addressed), so be it. I'll step away from all
the bikeshedding that this series has become.

-Emil