api stability (was is_ignored improvements...)

[Martin Pool]

On 17 May 2006, Aaron Bentley <aaron.bentley at utoronto.ca> wrote:
> Jan Hudec wrote:
> > It splits the WorkingTree.is_ignored method to ignored, which returns just
> > a boolean and ignored_by, which returns the pattern. is_ignored is deprecated
> > forwarder to ignored_by (to remain compatible).
> 
> That raises an interesting question: 0.8 was supposed to be our API
> stability release.  That would mean we can't deprecate anything until
> post 1.0, or at least not anything important.  So what should we do in
> cases like this?

API stability doesn't mean not deprecating functions; it mostly means
not removing them, and in particular not changing the meaning of
existing interfaces.

I think we should relax API stability from what was discussed prior to
0.8 -- freezing it too solidly now would be too soon.  Although many
features are in place we still have work to do, particularly in
performance, to get to a nice 1.0.  In any case, in Python it is rather
hard to determine exactly what behaviour a bzrlib client may be relying
on.  

I would prefer to focus on 

 * don't change existing apis gratuitously
 * use deprecations to warn when something is going away and how 
   calling code should be updated
 * improve api documentation and test coverage (so people know what apis
   they're supposed to use)
 * not letting any of these excessively impede actually improving bzr

-- 
Martin