|Re: [jgit-dev] API and versioning|
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.
Back to the top