[sugar] API policy
Marco Pesenti Gritti
Sun Oct 12 15:19:30 EDT 2008
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
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.
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.
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.
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.
I'm thinking of something along these lines:
Datastore service - stable
Presence service - stable
Window management - stable
Sugar public python package:
Thoughts very welcome, both about the general approach and about the state
of the existing interfaces!
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Sugar-devel