API breakages - file bugs / update HACKING.txt ?

[Martin Pool]

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

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

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

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.

-- 
Martin <http://launchpad.net/~mbp/>