API breakages - file bugs / update HACKING.txt ?

[Toshio Kuratomi]

Martin Pool wrote:
> On Wed, May 14, 2008 at 10:20 AM, Toshio Kuratomi <a.badger at gmail.com> wrote:
>> Jelmer Vernooij wrote:
>> Interesting.
>>
>> I didn't realize that policy existed but it has the potential to help distro
>> packagers.  Of course, there's two ways to interpret that stability:
>>
>> 1) Every six months, public API changes can be made.
>> 2) After six months of deprecation, a piece of public API can be changed.
>>
>> The first is much nicer for packagers as it means they have six months of
>> releases that they can include and know there won't be API breakage that
>> they have to consider when deciding whether to upgrade the packages in a
>> stable release.
>>
>> Assuming of course that this is a goal that bzr will start striving to meet
>> :-)
> 
> It's the second.  It's not a castiron guarantee as some APIs may be
> harder to preserve than we think is worthwhile, but it is something we
> strive for.  (At the moment 'worthwhile' basically depends on an
> educated guess as to whether the change is likely to be used by
> plugins; I think we do OK but it would be good to eventually test it)
> 
> The first does not seem so practical: not adding new APIs during that
> period would limit our development.
> 
Err... Perhaps I could have been clearer.  API additions aren't the 
problem.  Removing of API, new mandatory arguments to methods, etc are. 
  So you could add new API for six month and deprecate methods that they 
replace/need to get rid of in general.  And then have one release that's 
a housecleaning release where incompatibilities saved up for six months 
made.

> If a user or packager just wants to update every six months then I'd
> suggest they just take whatever is the latest release at that time and
> stick with that.  There is no need to take every single upgrade.
> Though obviously we do appreciate having more frequent packages
> available for distros.
> 
Yeah.  Unfortunately it's not that I only want to update every six 
months.  Many users (including myself and the various people who submit 
requests for updates every time a new bzr release is made :-) want to 
run the latest release due to performance enhancements, new features, 
repository format on the other end changing, etc.

The problem is that there's always the chance that there's people out 
there whose in-house plugin/application will break if I update to a new 
version with a piece of public API changed.  So I have the choice of 
either catering to those who want the latest release (of which I'm one) 
or those who *might* be broken by API changes.  So I usually try to 
interpret the API changes that do go into the release and decide whether 
they are drastic enough to keep them out of the already released 
versions of the distro.  Since I know you guys are already doing this to 
some extent (hence feeling that certain API is okay to change 
immediately whereas other pieces need to go through at least one cycle 
of deprecation) it would be great if I could just consume your knowledge 
of the situation.  But for that to occur, you'd either have to mark the 
major API changes differently from the minor changes in the NEWS file or 
have some convention around release numbers/release schedule so that I 
could figure it out.

Which is not to say that I don't deal with this problem now, it's just 
that the idea of six months without backwards incompatible API changes 
has a certain invigorating feel to it :-)

-Toshio