API breakages - file bugs / update HACKING.txt ?

[Toshio Kuratomi]

Martin Pool wrote:
> On Thu, May 22, 2008 at 12:18 PM, Toshio Kuratomi <a.badger at gmail.com> wrote:
>> 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.
> 
> With the caveats previously mentioned this is basically equivalent to
> what we do: everything is deprecated before being removed.  I don't
> really see how removing them in one big bang is much better.  (And in
> practice we do remove many things in big bangs, like I did with a
> recent patch, just not everything.)
> 
Having all breaks aggregated in releases six months apart a packager can 
do this pretty much on autopilot:

   bzr-1.0
   bzr-1.1
   [...]
   bzr-1.5

bzr-1.6 is the six month release with all sorts of backwards 
incompatible API.  Okay, only drop that into the development/unstable 
repository.  Close any further bugs asking for updates to bzr in 
released distro versions as won't fix, wait for the next distro release. 
If any security or crasher bugs appear, be prepared to backport to bzr-1.5.

Doing things in dribbles and drops we have something different:

   bzr-1.0
   bzr-1.1 (API removal that's been deprecated for six months, only 
affects ancient repo formats, and I have a bug report asking to 
update... okay we do it.)
   bzr-1.2 (Additional API, deprecation warning, no breaks,  package it).
   bzr-1.3 (API removal that's been deprecated for six months but it 
could affect plugins if the plugin needs to understand shared 
repositories.... Guess I better stop updating the packages for the 
released distro versions)

The package maintainer has to make more value judgements as to when it's 
safe to update a package to a later version if every release potentially 
expires a few pieces of deprecated API.

>> 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.
> 
> Can you explain more about what you want here?  We do already have a
> separate section for API changes.
> 
I very much appreciate that section!  What I'd like is a better feel for 
  what could break if I package this release for the distribution that's 
been sent out the door.  Were there tons of public plugins that had to 
be ported for deprecation warnings when this change first came out? 
Does this deal with code that probably no one has used outside of old 
Core bzr?


>> 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 :-)
> 
> If a plugin works with bzr's plugin API now, it should keep working
> (possibly with deprecation warnings) for at least six months.   I
> believe with a recent patch we'll no longer show the warnings to end
> users.

This is true if you count "Deprecation Warning == Not Working".  Which I 
agree with but also disagree with.  Since my conflict arises because I 
don't want to break things that end users may have written to solve 
their own in-house needs, I can't count on them to notice deprecation 
warnings and fix them (or have their company support group fix them) in 
a timely manner.  In this light, removing the warning for end user's 
makes my decision even harder.  I can't just blame the end-user for 
ignoring the warning and blithely not fixing it in the time allowed, I 
also have to consider that some end user's didn't even know their 
plugins were using deprecated functions until they suddenly stop working.

>  Basically this means that as long as people update their
> plugins every six months, they shouldn't break, and I think that's not
> too much to ask.
> 
As a developer for other projects, I agree with your sentiment 
whole-heartedly.  As a packager, I know that this doesn't help me make 
the decision whether to package the next version for the current release 
or only for the development release.

> That's the theory.  We probably don't always meet this in practice,
> for the reasons discussed earlier.  The main thing I can see to do
> there is to get more feedback from distributors, users, or plugin
> authors on when things break, so we can either fix the specific case
> or avoid that general class of breakage.  If someone set out to test
> manually or automatically the plugins they care about every time we do
> an rc that would be very useful.
> 
So I think the current system is pretty good for plugin developers. 
Having six months of deprecation warning to update the plugin you've 
written before the APIs go away seems reasonable and helpful.  But for a 
distribution, not having a branch of the software that's got a 
consistent API makes things harder.

Given that it is good for one target audience, I'm not asking for any 
changes; just explaining why it's not ideal for distributions.

-Toshio