Re: [jgit-dev] API and versioning

[Ferry Huberts <ferry.huberts@xxxxxxxxxx>]

On 01/17/2010 12:36 AM, Shawn O. Pearce wrote:
> Robin Rosenberg <robin.rosenberg@xxxxxxxxxx> wrote:
>> 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.
> 
> I think what we should do right now is:
> 
> Given a release numbering of 0.x.y:
> 
> - If x changes, APIs can be removed or semantics changed.
>   Applications linking against 0.x should take care before
>   moving to another 0.x release.
> 
> - If x stays same but y changes, no APIs have been removed, and no
>   semantic changes have been made.  New APIs however can be added.
> 
> That means in practice that other bundles importing JGit should use
> an import rule like ";version=[0.6.0,0.7.0)".
> 
> This also means we have to be very careful about using git describe
> to create a snapshot version number, basically tools/version.sh
> is wrong.
> 
> Whether or not we import using Require-Bundle or Import-Package
> doesn't much matter.  But Import-Package is I think preferred
> because...
> 
>> Is the ability to split bundles in the future a reason set requirements
>> at the package level?
> 
> I think that's the only reason for package level vs. bundle level.
> 

This proposal is not following OSGi versioning rules and common practices,
so maybe that's asking for trouble.

Checkout the OSGi spec for platform 4.2 at
http://www.osgi.org/Download/File?url=/download/r4v42/r4.core.pdf

On page 32 you'll see the definition for the version number.

In your proposal you're allowing api changes in minor releases, which is
not a common pratice. In light of still being in development I can
understand it though.

Maybe a better idea would be to allow new apis but no api changes or
removals in minor releases (shift your proposal from minor to major versions)

Also, be aware that 0.6.0.rc1 is _newer_ than 0.6.0




OSGi version number format
(from the book OSGi in Action from Manning):

One important concept you will visit over and over again in OSGi is a
version number. The OSGi specification defines a common version number
format used in a number of places throughout the specification. For this
reason it is worthwhile spending a few paragraphs exploring exactly what a
version number is in the OSGi world.

A version number is composed of three separate numerical component values
separated by dots; for example, 1.0.0 is a valid OSGi version number. The
first value is referred to as the major number, the second value as the
minor number, and the third value as the micro number. These names reflect
the relative precedence of each component value and is very similar to
other version numbering schemes, where version number ordering is based on
numerical comparison of version number components in decreasing order of
precedence; in other words 2.0.0 is newer than 1.2.0 and 1.10.0 is newer
than 1.9.9.

A fourth version component is possible, which is called a qualifier. The
qualifier can contain alphanumeric characters; for example, 1.0.0.alpha is
a valid OSGi version number with qualifier. When comparing version
numbers, the qualifier is compared using string comparison. As Figure 2.9
shows, this does not always lead to intuitive results; for example, while
1.0.0.beta is newer than 1.0.0.alpha, 1.0.0 is older than both.

                Higher Version----->
1.0.0  1.0.0.alpha  1.0.0.beta  1.0.1  1.1.0  1.1.1  1.2.0
+------+------------+-----------+------+------+------+------+
|      |            |           |      |      |      |      |
+------+------------+-----------+------+------+------+------+
Figure 2.9 OSGi versioning semantics can sometimes lead to non intuitive
results

In places where a version metadata is expected, if it is omitted, then it
defaults to 0.0.0. If a numeric component of the version number is
omitted, then it defaults to 0, while the qualifier defaults to an empty
string. For example, 1.2 is equivalent to 1.2.0.

One tricky aspect is that it is not possible to have a qualifier without
specifying all of the numeric components of the version. So, you cannot
specify 1.2.build-59, you must specify 1.2.0.build-59.

OSGi uses this common version number format for versioning both bundles
and Java packages.