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

[Quentin Glidic]

On 08/07/2016 13:00, Quentin Glidic 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.
>
> 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).
>
>
> Deprecation is just the other half of the work, for people wanting to
> avoid to-be-deleted stuff.
>
>
> I would define MIN, not MAX, because I think (my) software should just
> go forward.
>

Neverming, just make sure one can define the needed stuff from 
configure.ac. :-)

-- 

Quentin “Sardem FF7” Glidic