[jgit-dev] API and versioning

[Robin Rosenberg <robin.rosenberg@xxxxxxxxxx>]

Versioning is as ugly as Yoda, but doing it properly  may have some benefits, 
both for developers and users.

Until now everything has evolved very much from a practical point of view. We
add a new useful method where it seems to fit and we even drop things and
tell people to change their code. Everybody knows JGit is a fast moving target
so people are quite tolerant.

We have things in JGit that we know shouldn't look the way it does, and 
probably a few things that we haven't pondered much over. GitIndex is
marked deprecated because we have a partial replacement. The ref update
code was recently rewritten  What other stuff need we retire and what should
we hide as implementation details, i.e. only available within parts of JGit
and not outside.

Related to this is how we handle version numbers and bundles. I know
this works with jsch 1.41.1 so we set that as the required minimum version.

Should we declare version dependencies at the bundle or package level? I'm
not OSGi-fluent enough to tell the real difference, but bundle level seems
to match how we define versions better, i.e. we don't state anywhere that
this package is version 0.6.0, we do that at the bundle level and I think that
is the way most projects work. My feeling is that the package version 
dependency in OSGi is for those that actually assign versions at the package
level. Is the ability to split bundles in the future a reason set requirements
at the package level?

Another aspect is that there is tooling in Eclipse that we can use that help
check things at the bundle level. 

</ignorance-manifest>

-- robin