[Sugar-devel] Deprecation policy - was: About show-launcher option

[Manuel Quiñones]

2014/1/13 Daniel Narvaez <dwnarvaez at gmail.com>:
> On 13 January 2014 18:21, Manuel Quiñones <manuq at laptop.org> wrote:
>>
>> 2014/1/13 Daniel Narvaez <dwnarvaez at gmail.com>:
>> > IMO it should be deprecated and then removed at some point. In general,
>> > I
>> > think our approach to API stability is way too ad hoc. We need some
>> > rules,
>> > even if very simple, to define what is public, how/when it is
>> > deprecated,
>> > and how/when it is removed.
>>
>> What about?
>>
>> - when an API change arises, we discuss a time range for activities to
>> adapt
>>   the time range is measured in number of releases
>>
>> - we do the change in the code, leaving the old code
>>
>> - the deprecation is marked in the old code, adding a comment, logging a
>> warning
>>
>> - the deprecation is announced in each release notes,
>>   asking activity developers to update their code
>>   mentioning for how many number of releases it will keep working
>
>
> I think we should have a section in sugar-docs where we note the
> deprecations (and the time range). So we add them as we go.

I agree.  sugar-docs is the right place.

>>
>> - activity developers upload new versions to activities.sugarlabs.org,
>>   marking the corresponding Sugar version
>>
>> - after the aggreed time, the old code is removed
>>
>> This is more or less what we've been doing.  I think when the toolbars
>> API changed we gave about 1 year for adaptation.
>
>
> This sounds great to me.
>
> We just need a way to know what is public API and what is not. Maybe, for
> new code, everything is public unless it has the usual underscore or there
> are inline docs mentioning it's not public. For old code well... I guess we
> just decide case by case.

Yes, I think that's valid for old code too.  If you can import a
class, function or constant variable from the toolkit, its public.

> Also I think API is frozen on the day of the stable release, it's fine to
> make changes until then, otherwise it becomes really difficult to develop
> new API.

Agreed.

-- 
.. manuq ..