[Dev] HISTORY.txt

[Ted Leung]

On Nov 9, 2004, at 7:11 PM, Heikki Toivonen wrote:

> 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 don't particularly care what the format/file is.  Starting with 0.5 
we are going to have developer dogfood/platform goals for every 
release.  Once we do that, we'll need to document API changes.   That's 
not the same thing as saying that those API's are frozen, and I agree 
with what you write below about some kind of process for determining 
and reviewing public API.  I don't think that we need to do something 
heavyweight, but I also think we need to do more than nothing.

>
> 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.

I think that this is where we are going to start out at the end of 0.5.

>
> 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.

Yes, we don't have the kind of brittleness that you find in a large 
C/C++ program.  That's one of the benefits of using something like 
Java.

>
> 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?

The two widely used interface technologies in python seem to be the 
twisted interface implementation, and pyprotocols.

>
>
> So to summarize my view:
>
> * Get rid of HISTORY.txt
> * Maintain current practice of sending email to dev when commonly used 
> APIs change

I'd add:

Collect these e-mails into some document for each release

> * Start thinking about how we will finalize public APIs, but don't 
> actually start finalizing until much later
>

Ted