[sugar] API policy

[Simon Schampijer]

Marco Pesenti Gritti wrote:
> Hello,
> 
> for 0.84 we are planning to refactor and start stabilizing our public API.
> Given the high pressure to ship and the very early involvement of activity
> authors, our API quality is currently not as good as we would like it and is
> going to require substantial changes. An important part of the work is to
> figure out which guarantees we have and are able to provide at the moment
> and which policy we should adopt for the future. The following is an initial
> proposal, I would like to discuss it on the mailing list and in the next
> developer meetings.
> 
> The proposal applies to the following areas:
> 
> * Glucose dbus services: datastore and presence service.
> * Sugar public python package (provided by sugar-base and sugar-toolkit).
> * Window management protocols.
> 
> Each interface, being a python module, a service or a protocol can be in one
> of the following states. The state should be always explicitly documented.
> 
> UNSTABLE
> 
> Changes are possible at any time, except after the feature freeze of each
> release cycle, but they should be well documented. It should be used for API
> which requirements are not yet well enough to be able to settle on a stable
> interface. As Sugar mature we should aim to have as little as possible
> components in this state.
> 
> STABLE
> 
> No *incompatible* change is possible. The API should be well documented and
> a set of unit tests should prevent breakage. To be able to remove a stable
> interface it will have to first be deprecated.
> 
> DEPRECATED
> 
> Interfaces which are not useful anymore or are being replaced by better,
> incompatible ones should be deprecated and removed in the next *major*
> version. When deprecating an interface a replacement should be available and
> the migration to it well documented.
> 
> ---
> 
> Now, how to apply this in practice, starting with 0.84.
> 
> We should consider 0.82 as our first major release from an API point of
> view. The next one will be 1.0. I'm unhappy about this, but the reality is
> that Sugar has been deployed to a large user base already and there are lots
> of activities written for it. So we are forced to consider the part of our
> API which is useful to activities as stable.

So for example if I land a more powerful graphics/alert in 0.84 the old 
one would be deprecated at that moment and I would be able to remove the 
deprecated one completely by 1.0, correct?

I like your proposal, I think once we categorized it and documented it 
we made a huge step forward.

Thanks,
    Simon