For the most part I agree. But I do think there is value in versioning API packages that contain not only pure specification but also implementation. One real example is the OSGi package org.osgi.util.tracker package. This package contains the ServiceTracker API, but the ServiceTracker class also provides a significant amount of code behind the implementation of the API. Any bug fixes to the implementation contained in this package should be reflected by increasing the micro version of the package. Clients that only care about the pure specification would use the major.minor version to import, but if a bundle cannot work without some fix contained in a micro version of the package then the bundle should be able to import down to the micro version of the package.
Tom
From: John Arthorne <[EMAIL PROTECTED]>
To: Equinox development mailing list <equinox-dev@eclipse.org>
Date: 09/05/2008 11:00 AM
Subject: Re: [equinox-dev] .qualifier for export package?
We have qualifiers on bundles to support the notion of provisioning
"line-ups" (aka features) that list precise groups of IUs (one precise
build of a particular bundle). We *don't* have qualifiers on bundles so
that require-bundle statements can precisely choose a particular build of a
bundle to depend on, since this kind of coupling is too restrictive. We
don't have any mechanism today for defining line-ups of packages as we do
today with bundles, so qualifiers on packages currently have no value.
I think the use case you have in mind is picking a single bundle as a
starting point, and then expanding from that bundle based on its
dependencies (picking a thread in the ball of yarn and pulling on it to see
what comes out). In this scenario, if the bundle has an import-package
statement, and there are multiple builds of a bundle providing that package
in the repository, which one do you choose? The problem here as BJ points
out, is we would never want to couple our require-bundle/import-package
statements down to the qualifier level. This tight coupling completely
defeats the purpose of the component architecture where dependencies are
expressed at the level of specification. So, I don't think this
ball-of-yarn scenario can work in a development scenario where I want to
provision and test a particular build from a development repository
containing several builds. I think this scenario is only interesting when
run against repositories of officially released content such as the release
train repository, in which case any package that satisfies the import is
acceptable and qualifiers on either imports or exports are not needed.
More fundamentally, I may be alone here but I question the premise that
packages are simply finer-grained versions of bundles, and so everything we
do with bundle versions is still applicable at the package level. My
thinking is that a bundle is a container that holds specifications,
implementations, and other non-code artifacts. As such its version number
must have the flexibility to capture the fact that it contains not only
API, but other non-API artifacts that people may rely on (implementation
characteristics, extension points, documentation, source code, etc). When
someone has a require-bundle statement, they may want to express their
dependency on any one of the things that bundle contains. Thus it's
reasonable for someone to have a dependency range of, say, [1.0.2,2.0.0) on
a bundle, because they may rely on some non-code attribute of the bundle
that was introduced in version 1.0.2.
An API package, on the other hand, is pure specification. Version numbers
on packages can thus be expressed purely as a function of the API in the
package. If the API changes, the version changes, if the API doesn't
change, the version doesn't change. I don't even see a need for the
service segment on a package: major.minor should be enough to express
compatible and incompatible API changes. In my view the only value of the
push towards import-package is it moves dependencies from the container
(bundle), to the specification (package). It is not simply a push towards
dependency on finer-grained containers (which can be acheived simply by
making our bundles smaller). The great power of this shift is that it
allows for the flexibility of interchangeable implementations of that
specification. Moving to this world means you can no longer rely on non-API
characteristics of a package, so having an import-package define more than
a major.minor dependency defeats the purpose.
I think we need to make sure we agree on *why* moving from require-bundle
to import-package is valuable. That will held guide our thinking on the
semantics of package version numbers, where to use them, and the related
use cases around them. I would argue that today only a very small number
of Eclipse API packages are truly pure specification that one could
reasonably swap out the implementation of transparently. In my view these
are the only packages that are worth versioning at the package level. I
certainly think the *goal* should be moving towards this world of
specification-level dependencies (and thus use of import-package), but
that's not where we are today.).
John
Jeff McAffer <[EMAIL PROTECTED]>
Sent by:
[EMAIL PROTECTED] To
Equinox development mailing
list <equinox-dev@eclipse.org>
09/05/2008 01:33 AM cc
Subject
Please respond to Re: [equinox-dev] .qualifier
Equinox development mailing list for export package?
<equinox-dev@eclipse.org>
I'm certainly sympathetic to you thinking here. Having qualifiers in
import statements is ugly at best. The challenge is that in the dev cycle
the API of something may change many many times. This would lead to quite
visible changes in unreasonable ways. For example, say we introduce some
API and then "break" it several times as we refine in the dev cycle. Then
the first release of the API might have version 42.23.27 or some such.
Trying to manage API semantics during the dev/release cycle seems like
overkill. Clearly that is an over done example but you get the point I
hope.
Lets step back for a second. Some goals in decreasing order of
priority/importance.
Goal #1: ensure that at least all API packages have version numbers on the
exports.
Goal #2: be able to eat our own dog food wrt provisioning and version
management during the dev cycle.
Good news is that #1 is likely agreed to and *all* we have to do is put the
initial version numbers on the current packages and then have the tooling
help people manage them according to the current versioning model.
The proposal for using .qualifier was actually one possible implementation
of goal #2. #2 is interesting because eating our own dog food seems to
greatly increase the likelihood of our technology being good/useful.
Without some sort of increasing version number on the packages, p2 for
example, will have a hard time figuring out what to give you cause
everything will look the same to it.
Can anyone think of another way of enabling #2? Of the top of my head I'm
thinking that something like the odd/even version pattern might help...
Jeff
BJ Hargrave wrote:
If you change API during dev cycle, that is the proper time to also change
the major or minor version. That is the whole point. I would assume that
API tooling will complain until you do so. Just changing the qualifier is
insufficient to capture an API change. Also, I think that last thing we
want to see are bundles using qualifiers in import package statements! So
if you use qualifier to denote API change during dev, then other bundles
will need to import using qualifiers to ensure they wire to the desire API
if they use it. UGLY!
Qualifiers are useful to capture implementation changes. But API is a
specified thing that changes deliberately and (hopefully) slowly and its
version is not subject to implementation.
--
BJ Hargrave
Senior Technical Staff Member, IBM office: +1 386 848 1781
OSGi Fellow and CTO of the OSGi Alliance mobile: +1 386 848 3788
[EMAIL PROTECTED]
From: Jeff McAffer <[EMAIL PROTECTED]>
To: Equinox development mailing list <equinox-dev@eclipse.org>
Date: 2008/09/03 06:16 AM
Subject: Re: [equinox-dev] .qualifier for export package?
I understand your hestiation and actually agree with you from the "released
code" point of view. However, we spend a lot of time dealing with code and
API that is in development. If we are to have any hope of provisioning and
managing that, we need to know the difference between the various
iterations of the packages. For example, when someone adds an API during
the dev cycle and you want use it, you need to import the right version of
the package to ensure you get it. Changing the first three segments
version number of the package for every change done in the dev cycle feels
too disruptive.
To a certain extent this could be handled in the provisioning system but
that would force the situation of bundles in a particular context (e.g., a
build "lineup"). That is, bundles would no longer be completely/accurately
self-describing.
Jeff
BJ Hargrave wrote:
I would be extremely cautious about using qualifier on package versions. I
must say that I have never seen it done.
It seems an over specification. I think that having build tools to advise
you to increment the micro is more than sufficient.
--
BJ Hargrave
Senior Technical Staff Member, IBM office: +1 386 848 1781
OSGi Fellow and CTO of the OSGi Alliance mobile: +1 386 848 3788
[EMAIL PROTECTED]
From: Thomas Watson/Austin/[EMAIL PROTECTED]
To: Equinox development mailing list <equinox-dev@eclipse.org>
Date: 2008/09/02 10:45 AM
Subject: Re: [equinox-dev] .qualifier for export package?
Before recommending every package uses a qualifier I have the following
concerns:
1) In Eclipse we have loads of packages. We better make sure all identical
qualifier Strings are shared (interned etc.) for performance reasons. Today
when loading from a cached state we share identical Version objects.
Because package versions are managed independently we will end up with lots
of different versions that have the same qualifier exported by a bundle. We
also will limit the ability to share Version objects across bundles because
each will use a different qualifier (unless we happen to use the same CVS
tag).
2) The qualifier will change even in cases where no code was touched in the
package. I'm not sure this is a valid concern. The code got recompiled so
perhaps changing the version qualifier is warranted. But we need to think
about the consequences. For example, I can see API tooling start to
complain that the micro version of a package should be increased to
indicate a bug "fix" when comparing the package versions with a base line.
It will notice that the qualifier changed from a previous release but the
micro version was not increased.
3) What about versions of packages which we do not maintain the API for at
Eclipse. Things like org.osgi.* and orbit bundles. Shouldn't we use the
version the producers of the API have defined? Adding a qualifier here does
not seem right, especially if a qualifier is already defined by the
producers.
On the surface this sounds like a fine idea, and I am not completely
against it. But I would like to take the first step of versioning the
Eclipse API packages first to see what all the issues are with independent
package versioning. I'm sure we will run into other hurdles along the way.
For example, how does a developer maintain the version of a split package
across all the bundles the package is split?
Tom
Inactive hide details for "Chris Aniszczyk" ---08/31/2008 02:46:34 PM---On
Sun, Aug 31, 2008 at 5:53 AM, Jeff McAffer < [EMAIL PROTECTED]"Chris Aniszczyk"
---08/31/2008 02:46:34 PM---On Sun, Aug 31, 2008 at 5:53 AM, Jeff McAffer <
[EMAIL PROTECTED]
From: "Chris Aniszczyk" <[EMAIL PROTECTED]>
To: "Equinox development mailing list" <equinox-dev@eclipse.org>
Date: 08/31/2008 02:46 PM
Subject: Re: [equinox-dev] .qualifier for export package?
On Sun, Aug 31, 2008 at 5:53 AM, Jeff McAffer <[EMAIL PROTECTED]> wrote:
As version numbers on packages become more prevalent does it start making
sense to use .qualifier on them in addition to bundle version numbers? The
logic here is the same as for bundles. we rev the version number of the
bundle to match the most extreme change for that release. in between if hte
provisioning system is going to do its job, it needs to have different
version numbers. Teh .qualifier allows for the auto-qualification of bundle
version numbers. The same is true for folks using import/export package.
+1
In PDE, I plan on releasing some builder logic to flag exported packages
without versions with a warning in M2. API Tooling also has items in plan
that deal with package versioning, but that will be post M2
Thoughts for how/if this should be introduced?
I say before M2, we formulate a plan across the Eclipse proper projects to
deal with versions on package exports. We can than look at pushing that
plan to other Eclipse.org projects as a best practice once we get the hang
of it.
--
Cheers,
~ Chris Aniszczyk_______________________________________________
equinox-dev mailing list
equinox-dev@eclipse.org
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@eclipse.org
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@eclipse.org
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@eclipse.org
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@eclipse.org
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@eclipse.org
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@eclipse.org
https://dev.eclipse.org/mailman/listinfo/equinox-dev
<<inline: graycol.gif>>
<<inline: ecblank.gif>>
_______________________________________________ equinox-dev mailing list equinox-dev@eclipse.org https://dev.eclipse.org/mailman/listinfo/equinox-dev
