[sugar] API policy

[Marco Pesenti Gritti]

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.

I'm thinking of something along these lines:

Datastore service - stable
Presence service - stable
Window management - stable

Sugar public python package:

Stable:

sugar.presence.*
sugar.graphics.*
sugar.activity.activity
sugar.activity.activityhandle
sugar.activity.activityservice
sugar.bundlebuilder
sugar.main
sugar.network
sugar.datastore.datastore
sugar.logger
sugar.mime
sugar.env

Unstable:

sugar.util
sugar.bundle.*
sugar.activity.activityfactory
sugar.datastore.dbus_helpers
sugar.wm

Deprecated:

sugar.profile
sugar.activity.registry
sugar.clipboard.*

---

Thoughts very welcome, both about the general approach and about the state
of the existing interfaces!

Thanks,
Marco
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.laptop.org/pipermail/sugar/attachments/20081012/82ff534c/attachment.htm