What APIs to check versions of?

[Robert Collins]

On Tue, 2008-10-07 at 17:52 +0200, Jelmer Vernooij wrote:
> Hi Rob,
> 
> Thanks for providing fixes for those bzrlib.api functions. There doesn't
> appear to be a lot of documentation as to of what objects I should check
> the API. Can you please comment?

So it boils down to finding a good compromise - we could version every
single method if we wanted, or class, or module.

> There are a few obvious ones:
> 
> bzrlib.config.AuthenticationConfig
> bzrlib.config.TreeConfig
> bzrlib.config.GlobalConfig
> bzrlib.config.LocationConfig

config is a pretty stable interface, and I think all the changes there
in recent times have been done compatibly; so with a version marker on
it just checking bzrlib.config is probably suitable.

> bzrlib.command.Command
> bzrlib.option.Option
> bzrlib.transport.Transport

Like wise these three.

> bzrlib.bzrdir.BzrDir
> bzrlib.bzrdir.BzrDirFormat
> bzrlib.bzrdir.Converter

I think BzrDir/BzrDirFormat might have had an api break, and its
certainly a key piece performance wise so its more likely that we'll
have changes we need to make.

> bzrlib.inventory.Inventory

I'm hoping to make a change here that will affect providers of
inventories but is compatible for clients for some time - just
deprecating access to .root in favour of a .root_id.

> bzrlib.repository.RepositoryFormat
> bzrlib.repository.Repository

This has had a number of incompatible changes made to it, but I think
we're getting past the most turbulent times now.

> bzrlib.repository.InterRepository
> bzrlib.repository.RootCommitBuilder
> bzrlib.branch.Branch
> bzrlib.branch.BranchFormat
> bzrlib.workingtree.WorkingTree
> bzrlib.workingtree.WorkingTreeFormat
> bzrlib.revisionspec.RevisionSpec
> bzrlib.tag.BasicTags
> bzrlib.revision.Revision
> bzrlib.registry.Registry
> bzrlib.branch.BranchCheckResult
> bzrlib.branch.PullResult
> bzrlib.lockdir.LockDir
> bzrlib.versionedfile.VersionedFiles
> bzrlib.revisiontree.RevisionTree
> 
> What about e.g. custom log handlers? Should I check bzrlib.log or
> bzrlib.log.properties_handler_registry or something else?
> 
> What about e.g. utility modules like urlutils? Are those guaranteed to
> just never break API? Should I check the API version of each individual
> function or perhaps of the module? The latter should be doable, the
> first would be very impractical (and tricky to make sure we check for
> each function). 
> 
> Would it perhaps make sense for the get_.*_api functions to check
> recursively up until it finds an object that has an API version set?
> E.g. when invoked on bzrlib.branch.Branch, first check
> bzrlib.branch.Branch, then bzrlib.branch, then bzrlib.

IIRC we didn't do that because its actually hard given a random object
to be sure of its namespace; it makes the interface start to rely on
class mechanics. It also conflates the namespace with versioning, which
is more of a problem, because code organisation and code backwards
compatibility are different things.

I'd be inclined to start by using modules - e.g. bzrlib.lockdir, and see
if that is granular enough. It would be easy to be over-granular.

Also, in case it wasn't clear - you can use the check functions at
runtime, not just when you are imported. So you might check enough to be
confident your format can be registered ok, and when you first probe for
an svn tree, then check the rest. Or you can check up front - the checks
should be cheap after paying the cost to load the modules.

-Rob

-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20081008/72bc8804/attachment.pgp