<div dir="ltr">Hello,<br><br>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.<br>
<br>The proposal applies to the following areas:<br><br>* Glucose dbus services: datastore and presence service.<br>* Sugar public python package (provided by sugar-base and sugar-toolkit).<br>* Window management protocols.<br>
<br>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.<br><br>UNSTABLE<br><br>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.<br>
<br>STABLE<br><br>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.<br><br>
DEPRECATED<br><br>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.<br>
<br>---<br><br>Now, how to apply this in practice, starting with 0.84.<br><br>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.<br>
<br>I'm thinking of something along these lines:<br><br>Datastore service - stable<br>Presence service - stable<br>Window management - stable<br><br>Sugar public python package:<br><br>Stable:<br>
<br>
sugar.presence.*<br>
sugar.graphics.*<br>
sugar.activity.activity<br>
sugar.activity.activityhandle<br>
sugar.activity.activityservice<br>
sugar.bundlebuilder<br>
sugar.main<br>
sugar.network<br>
sugar.datastore.datastore<br>
sugar.logger<br>
sugar.mime<br>
sugar.env<br>
<br>Unstable:<br><br>sugar.util<br>sugar.bundle.*<br>sugar.activity.activityfactory<br>sugar.datastore.dbus_helpers<br>sugar.wm<br><br>Deprecated:<br><br>sugar.profile<br>
sugar.activity.registry<br>
sugar.clipboard.*<br>
<br>---<br><br>Thoughts very welcome, both about the general approach and about the state of the existing interfaces!<br><br>Thanks,<br>Marco<br></div>