[Dev] HISTORY.txt

[Heikki Toivonen]

Ted Leung wrote:
> We are going to have API's that developers will use.  When those API's 
> change, we need to document that.  Changes that will break external 
> parcels between milestones are the changes that I think we should be 

I don't think a changelog is the best way for this. And we don't yet 
have real external parcels. Also, I am not sure how much effort we 
should put into informing people of changes to APIs that we haven't 
finalized yet. (I think the way we have been doing so far is ok - 
whenever Andi changes an API he sends out a note to dev, for example.) 
And once we finalize something, it shouldn't change except under very, 
very exceptional situations.

I think we should strive towards the goal of a set of public APIs that 
we promise will always work, barring those very, very exceptional 
situations.

Except for the repository, I don't think we have any parts of Chandler 
even close to finalized form. And even with the repository, I wouldn't 
feel comfortable thinking about frozen interfaces until after 6 months 
from now.

So how do we get to those APIs? The way Mozilla does this (I don't yet 
have an opinion on how closely we should match the Mozilla model on 
this) is by having having an API review to freeze public APIs that will 
never change. To freeze an API in Mozilla would require something like this:

* There must be a need for this public frozen API (for example plugins)
* The API must have been in use for a reasonable period of time 
(otherwise, you won't have enough experience using it to know what the 
final form should be like)
* The API must go through an API review
* The API review effectively notifies people that the API is under 
consideration to be frozen, and asks people for comments. The API may be 
changed based on that feedback. The API will be formatted to frozen API 
guidelines (if it isn't already), for example it must be written in IDL, 
every interface, method, parameter and return value documented, and the 
indicator that the interface is frozen will be prominently displayed). 
The API may remain in proposed frozen form for months before it is 
actually frozen. It resembles a standards process.

Mozilla explicitly says that any non-frozen interface can and will 
change without notice, and people should not be using them unless they 
are willing to go through the pain of changing their applications when 
the APIs change.

On the other hand, frozen APIs are very seriously frozen. I have only 
vague memory of one frozen interface being changed (although there quite 
likely have been more). If an interface is later found out to be broken, 
a lot of effort goes into maintaining it even when a new API will be 
created (nsIFoo, nsIFooExtended, ...)


Now, we don't have IDL, and Python gives a little more flexibility 
compared to Mozilla's situation.

What is the best way to do interfaces in Python? Should we go towards 
the model that Twisted uses, with clear interfaces (check out 
twisted.internet.interfaces)? Or will we freeze modules/classes that 
contain implementations?


So to summarize my view:

* Get rid of HISTORY.txt
* Maintain current practice of sending email to dev when commonly used 
APIs change
* Start thinking about how we will finalize public APIs, but don't 
actually start finalizing until much later

-- 
   Heikki Toivonen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 249 bytes
Desc: OpenPGP digital signature
Url : http://lists.osafoundation.org/pipermail/dev/attachments/20041109/edd521ca/signature.bin