<div dir="ltr">On 13 January 2014 18:21, Manuel Quiñones <span dir="ltr"><<a href="mailto:manuq@laptop.org" target="_blank">manuq@laptop.org</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
2014/1/13 Daniel Narvaez <<a href="mailto:dwnarvaez@gmail.com">dwnarvaez@gmail.com</a>>:<br>
> IMO it should be deprecated and then removed at some point. In general, I<br>
> think our approach to API stability is way too ad hoc. We need some rules,<br>
> even if very simple, to define what is public, how/when it is deprecated,<br>
> and how/when it is removed.<br>
<br>
What about?<br>
<br>
- when an API change arises, we discuss a time range for activities to adapt<br>
  the time range is measured in number of releases<br>
<br>
- we do the change in the code, leaving the old code<br>
<br>
- the deprecation is marked in the old code, adding a comment, logging a warning<br>
<br>
- the deprecation is announced in each release notes,<br>
  asking activity developers to update their code<br>
  mentioning for how many number of releases it will keep working<br></blockquote><div><br></div><div>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.<br>
</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
- activity developers upload new versions to <a href="http://activities.sugarlabs.org" target="_blank">activities.sugarlabs.org</a>,<br>
  marking the corresponding Sugar version<br>
<br>
- after the aggreed time, the old code is removed<br>
<br>
This is more or less what we've been doing.  I think when the toolbars<br>
API changed we gave about 1 year for adaptation.</blockquote><div><br></div><div>This sounds great to me.<br><br>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.<br>
<br></div><div>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.<br></div></div></div></div>