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

[Daniel Narvaez]

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.


> - 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.

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sugarlabs.org/archive/sugar-devel/attachments/20140114/024f8573/attachment-0001.html>