[sugar] API policy
Simon Schampijer
simon
Thu Oct 16 08:55:27 EDT 2008
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
More information about the Sugar-devel
mailing list