You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@sling.apache.org by Felix Meschberger <fm...@gmail.com> on 2009/11/09 16:35:27 UTC
Version Numbers
Hi all,
<warning>lengthy mail</warning>
In comments to SLING-1176 Ian Boston wrote:
"The exports in bundle/api/pom.xml look like they might
become problematic from a support point of view, although
we probably cant avoid this.
[...]
[The problem is the] manual maintenance of the version numbers.
(not a big problem bit needs to be done)"
I agree, that this is a problem. Let me reasonate on this a bit ;-)
As a reference you might want to read my latest blog post at [1] and
also what the Eclipse guys have to say [2] (great read, btw).
So for Sling, we have three kinds of version numbers: (1) Big Sling
releases, (2) Sling bundles, and (3) exported packages.
For (1) we have already an ample solution in that we just increase the
number from release to release. Just remember that a "big Sling release"
is a convenience release of existing released Sling bundles.
For (2) version numbers are just defined as the <version> element of the
bundle's POM. The only restriction here is, that we decided to use even
numbers for releases and odd numbers for SNAPSHOTs. Whether and when
which version part is increased is not codified.
For (3) the situation is more problematic since there are a number of
places to set exported package version number: In a packageinfo file
inside the package (picked up by the Bundle plugin to set the export
version) or explicitly in the <Export-Package> element of the Bundle
plugin configuration or by reference to the bundle version number using
the ${pom.version} variable.
Upto now, we mostly used the ${pom.version} notation linking the
exported package version to the bundle version. This works well for
bundles with simple exports. For more complicated bundles, specifically
for bundles with multiple exported packages which may evolve
independently, this does not work well.
Consider for example the Sling API bundle, which exports 7 packages.
Each of which may evolve independently. Now the resource package is
enhanced causing a minor version increase. Should the version numbers of
the other exports also be increased ? Thus acting as if there was some
API change ?
I would say, no. Particularly if some API implementation bundle is
restricting the import version of the API implemented. Such an
implementation would immediately stop working because the version has
been increased. But since there has been no change, the implementation
would still be correct.
So, I think, we should evolve the exported package versions
independently from each other and possibly even independently from the
bundle version.
This places more burden on the developer when deciding on the exported
package version - in fact this requires such a decision as compared to
have Maven take the decision by just setting the bundle version.
The only problem is: Where shall this be noted ? In the POM or in the
packageinfo file ? If we would place the packageinfo file just beneath
the class source files, I would say, in the packageinfo file.
But this would require defining the class source locations as resource
location in the POM (at least for packageinfo) files.
I am not sure ....
WDYT ?
Regards
Felix
[1] http://blog.meschberger.ch/2009/10/on-version-numbers.html
[2] http://wiki.eclipse.org/index.php/Version_Numbering
Re: Version Numbers
Posted by Bertrand Delacretaz <bd...@apache.org>.
Hi,
I tend to agree with Carsten on this one - having per-package OSGi
version numbers makes sense, but without tools to manage that the risk
of making a mess is high.
I would be +1 for having per-package version numbers if there was a
tool to compute/enforce those numbers: using svn to compare code
between bundle releases would let us know when a package version
number needs to change - that doesn't seem too complicated, but we
don't have such a tool ;-)
Right now I'm for continuing to have bundle version == package version.
That's a bit of a waste when only one package of a bundle actually
changes between bundle releases, but if we find that happening too
often we might want to just split that bundle into multiple bundles.
-Bertrand
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Just to be clear: IMHO a burden on a small number of developers (namely
definers of API and implementors of that same API) is much preferable to
burdons placed on our users !
We are the specialists, we know more, so we should be able to do more
and bury an additional burden. It is, in fact, not a big one for us. We
just have to get used to it ...
So no matter whether we have tooling or not, it is IMHO our task to take
that burden. As I said, the main cause of issues in Sling is probably
the Sling API bundle.
Regards
Felix
Bertrand Delacretaz schrieb:
> On Tue, Nov 17, 2009 at 9:24 AM, Carsten Ziegeler <cz...@apache.org> wrote:
>> ...Again, with proper tooling all of this is no problem....
>
> And we don't have such tooling, or do we?
>
> I see the logic in Felix's reasoning, but without tooling I think the
> burden on developers (and on users trying to make sense of a myriad
> version numbers) is too high. Not because we are too lazy to do it,
> but because more work means more room for failure.
>
> As for tooling, something that computes digests on the source code of
> packages, and checks that the version numbers change when the
> aggregated digests of a given package change, would at least make it
> possible to know when package version numbers need to change.
>
> Also, maybe this version management scheme makes sense for a small
> number of our bundles (like the API bundles), in which case we might
> agree to use this scheme just for those few bundles - which also
> rarely change, making that more manageable.
>
> -Bertrand
>
Re: Version Numbers
Posted by Karl Pauls <ka...@gmail.com>.
On Tue, Nov 17, 2009 at 9:47 AM, Bertrand Delacretaz
<bd...@apache.org> wrote:
> On Tue, Nov 17, 2009 at 9:24 AM, Carsten Ziegeler <cz...@apache.org> wrote:
>> ...Again, with proper tooling all of this is no problem....
>
> And we don't have such tooling, or do we?
I know that the eclipse pde people are working on this kind of stuff.
I think it might be possible to build something around their api
tools:
http://eclipsesource.com/blogs/2009/07/08/osgi-eclipse-and-api-management/
Not sure how easy it would be to use it for our purposes but it sure
would be great to have something in this area.
Regarding the burden on the user see my other mail where i show how
bnd can be configured to do the correct thing based on the
versionpolicy feature of bnd.
regards,
Karl
> I see the logic in Felix's reasoning, but without tooling I think the
> burden on developers (and on users trying to make sense of a myriad
> version numbers) is too high. Not because we are too lazy to do it,
> but because more work means more room for failure.
>
> As for tooling, something that computes digests on the source code of
> packages, and checks that the version numbers change when the
> aggregated digests of a given package change, would at least make it
> possible to know when package version numbers need to change.
>
> Also, maybe this version management scheme makes sense for a small
> number of our bundles (like the API bundles), in which case we might
> agree to use this scheme just for those few bundles - which also
> rarely change, making that more manageable.
>
> -Bertrand
>
--
Karl Pauls
karlpauls@gmail.com
Re: Version Numbers
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Tue, Nov 17, 2009 at 9:24 AM, Carsten Ziegeler <cz...@apache.org> wrote:
> ...Again, with proper tooling all of this is no problem....
And we don't have such tooling, or do we?
I see the logic in Felix's reasoning, but without tooling I think the
burden on developers (and on users trying to make sense of a myriad
version numbers) is too high. Not because we are too lazy to do it,
but because more work means more room for failure.
As for tooling, something that computes digests on the source code of
packages, and checks that the version numbers change when the
aggregated digests of a given package change, would at least make it
possible to know when package version numbers need to change.
Also, maybe this version management scheme makes sense for a small
number of our bundles (like the API bundles), in which case we might
agree to use this scheme just for those few bundles - which also
rarely change, making that more manageable.
-Bertrand
Re: Version Numbers
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Tue, Nov 17, 2009 at 11:28 AM, Carsten Ziegeler <cz...@apache.org> wrote:
> ...Yes, I think we should give this a try....
>
> ...But for most of our bundles this is trivial anyway as we usually have a
> single exported package - the only "beast" is the api bundle, but I
> guess we can manage this one....
Ok, so can we limit this experiment to the sling api bundle for now?
-Bertrand
Re: Version Numbers
Posted by Carsten Ziegeler <cz...@apache.org>.
Felix Meschberger wrote:
>
> Well, this is actually handled by the bnd library used by the
> maven-bundle-plugin: This extracts the necessairy versions to create the
> Import-Package statements correctly from the referred to libraries.
>
> So, if you -- as suggested before -- always refer to the lowest version
> of the dependency which satisifies your need, you as a user of the API,
> are perfectly on the good side and don't need to worry.
>
> As long as you do not need new functionality, keep the existing
> dependency. Increase the dependency version if you need new
> functionality and have the bundle plugin/bnd library do the rest for you.
>
Yes, I think we should give this a try.
For the tooling there is the Apache Felix Sigil stuff for Eclipse -
which has some basic stuff in it, one could use - but it doesn't work
with Maven (yet).
But for most of our bundles this is trivial anyway as we usually have a
single exported package - the only "beast" is the api bundle, but I
guess we can manage this one.
Carsten
--
Carsten Ziegeler
cziegeler@apache.org
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Alexander Klimetschek schrieb:
> On Tue, Nov 17, 2009 at 10:47, Karl Pauls <ka...@gmail.com> wrote:
>> hence, why not do the following:
>>
>> version api packages independently along the line of what Felix is suggesting
>> version implementation packages based on the bundle version (and
>> possibly make importers be hard coupled by using the symbolic-name
>> requirement).
>
> Sounds good. But...
>
> On Tue, Nov 17, 2009 at 09:24, Carsten Ziegeler <cz...@apache.org> wrote:
>> The only problem I still have is that in the end there is no correlation
>> between the bundle version and the package versions. If for example a
>> bundle has two packages A and B, we start with version 0.1 for both
>> packages -> bundle version 0.1; then we change B to 0.2 -> bundle
>> version 0.2 but A is still 0.1.
>> Now we change A to 0.2 as well which would result in what bundle
>> version? 0.2.2?
>
> ... I think this case is still unclear to me. Even with good tooling
> this is not really solved. Because we only talk about tooling for the
> creators of packages. The users use maven, the maven repo, or simple
> INSTALL.txt files with list of jar files. With those it is hard to
> find out the actual package versions behind the big version number on
> the bundle/jar file. Thus we make it harder for users, not easier as
> Felix's goal righteously is.
Well, this is actually handled by the bnd library used by the
maven-bundle-plugin: This extracts the necessairy versions to create the
Import-Package statements correctly from the referred to libraries.
So, if you -- as suggested before -- always refer to the lowest version
of the dependency which satisifies your need, you as a user of the API,
are perfectly on the good side and don't need to worry.
As long as you do not need new functionality, keep the existing
dependency. Increase the dependency version if you need new
functionality and have the bundle plugin/bnd library do the rest for you.
Regards
Felix
Re: Version Numbers
Posted by Alexander Klimetschek <ak...@day.com>.
On Tue, Nov 17, 2009 at 10:47, Karl Pauls <ka...@gmail.com> wrote:
> hence, why not do the following:
>
> version api packages independently along the line of what Felix is suggesting
> version implementation packages based on the bundle version (and
> possibly make importers be hard coupled by using the symbolic-name
> requirement).
Sounds good. But...
On Tue, Nov 17, 2009 at 09:24, Carsten Ziegeler <cz...@apache.org> wrote:
> The only problem I still have is that in the end there is no correlation
> between the bundle version and the package versions. If for example a
> bundle has two packages A and B, we start with version 0.1 for both
> packages -> bundle version 0.1; then we change B to 0.2 -> bundle
> version 0.2 but A is still 0.1.
> Now we change A to 0.2 as well which would result in what bundle
> version? 0.2.2?
... I think this case is still unclear to me. Even with good tooling
this is not really solved. Because we only talk about tooling for the
creators of packages. The users use maven, the maven repo, or simple
INSTALL.txt files with list of jar files. With those it is hard to
find out the actual package versions behind the big version number on
the bundle/jar file. Thus we make it harder for users, not easier as
Felix's goal righteously is.
Regards,
Alex
--
Alexander Klimetschek
alexander.klimetschek@day.com
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Ok, I am done for now with the page [1]. Over the course of an hour or
two, it should also be synchronized to the site.
Note, that I still kept the unsynchronized version numbers because in
practice the best we can do is apply the same semantics to package and
bundle versions when it comes to increasing. But we will not be able to
keep them in sync in any way -- unless we are ready to have "holes"
(which would also not be a bad thing per se.
Please comment. Thanks.
Regards
Felix
Felix Meschberger schrieb:
>
> Bertrand Delacretaz schrieb:
>> On Tue, Nov 17, 2009 at 3:28 PM, Ian Boston <ie...@tfd.co.uk> wrote:
>>> ...I think package1 should be allowed to be v 1.2 and then the bundle version
>>> would be 1.2.1
>>>
>>> If the package versions jump the range of versions will diverge within a
>>> single bundle and the rate of version number change of the bundle itself
>>> will accelerate (sort of positive feedback). Over time I think this will
>>> lead to confusion since there could be many missing versions of each package
>>> and a highly complex bundle version history.
>>>
>>> Incrementing of package version numbers without holes in the sequence for
>>> each package, coupled with sub-minor releases of the bundle will lead to a
>>> converging version history that IMHO will be easier to understand and track
>>> (its hard enough for a OSGi newbee as it is)
>>>
>>> Only when one of the packages ups its version to 1.3 does the bundle move to
>>> v1.3.0
>>>
>>> Did that make sense ?...
>> Mostly yes, but I think we need a wiki page with several examples like
>
> Is ok for me, too.
>
> I am not really sure how to increase version numbers of bundles mixing
> exported API and implementation, like for example the Sling Engine
> bundle ...
>
>> the ones Felix showed and like yours above.
>
> I have started a page on this (part of the offical documentation) at [1]
>
>> Did I mention this was going to be confusing? ;-)
>
> Well, only in the first place, you get used to it ;-)
>
> Regards
> Felix
>
> [1] http://cwiki.apache.org/SLINGxSITE/version-policy.html
>
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Bertrand Delacretaz schrieb:
> On Tue, Nov 17, 2009 at 3:28 PM, Ian Boston <ie...@tfd.co.uk> wrote:
>> ...I think package1 should be allowed to be v 1.2 and then the bundle version
>> would be 1.2.1
>>
>> If the package versions jump the range of versions will diverge within a
>> single bundle and the rate of version number change of the bundle itself
>> will accelerate (sort of positive feedback). Over time I think this will
>> lead to confusion since there could be many missing versions of each package
>> and a highly complex bundle version history.
>>
>> Incrementing of package version numbers without holes in the sequence for
>> each package, coupled with sub-minor releases of the bundle will lead to a
>> converging version history that IMHO will be easier to understand and track
>> (its hard enough for a OSGi newbee as it is)
>>
>> Only when one of the packages ups its version to 1.3 does the bundle move to
>> v1.3.0
>>
>> Did that make sense ?...
>
> Mostly yes, but I think we need a wiki page with several examples like
Is ok for me, too.
I am not really sure how to increase version numbers of bundles mixing
exported API and implementation, like for example the Sling Engine
bundle ...
> the ones Felix showed and like yours above.
I have started a page on this (part of the offical documentation) at [1]
>
> Did I mention this was going to be confusing? ;-)
Well, only in the first place, you get used to it ;-)
Regards
Felix
[1] http://cwiki.apache.org/SLINGxSITE/version-policy.html
Re: Version Numbers
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Tue, Nov 17, 2009 at 3:28 PM, Ian Boston <ie...@tfd.co.uk> wrote:
> ...I think package1 should be allowed to be v 1.2 and then the bundle version
> would be 1.2.1
>
> If the package versions jump the range of versions will diverge within a
> single bundle and the rate of version number change of the bundle itself
> will accelerate (sort of positive feedback). Over time I think this will
> lead to confusion since there could be many missing versions of each package
> and a highly complex bundle version history.
>
> Incrementing of package version numbers without holes in the sequence for
> each package, coupled with sub-minor releases of the bundle will lead to a
> converging version history that IMHO will be easier to understand and track
> (its hard enough for a OSGi newbee as it is)
>
> Only when one of the packages ups its version to 1.3 does the bundle move to
> v1.3.0
>
> Did that make sense ?...
Mostly yes, but I think we need a wiki page with several examples like
the ones Felix showed and like yours above.
Did I mention this was going to be confusing? ;-)
-Bertrand
Re: Version Numbers
Posted by Ian Boston <ie...@tfd.co.uk>.
On 17 Nov 2009, at 06:48, Alexander Klimetschek wrote:
>>>> * Extend package2 API, thus:
>>>> version 1.2.0
>>>> exports package1,version 1.1
>>>> exports package2,version 1.2
>>>> contains implementation code...
>>>
>>> And now, if package1's API changes (version 1.2), what's the bundle
>>> version number?
>>
>> no, version 1.3
>>
>>>
>>> I'd suggest 1.3.0, i.e. bump up the middle number whenever a package
>>> version changes.
>>
>> Exactly, because package1 becomes 1.3
>>
>> (middle number == minor version number)
>
> That sounds good to me. That way one could ignore the package versions
> if he likes to (I know you shouldn't, but it's more natural for people
> new to osgi).
>
> +1 for "testing it" with the sling api bundle.
+1 for testing, however
I think package1 should be allowed to be v 1.2 and then the bundle
version would be 1.2.1
If the package versions jump the range of versions will diverge within
a single bundle and the rate of version number change of the bundle
itself will accelerate (sort of positive feedback). Over time I think
this will lead to confusion since there could be many missing versions
of each package and a highly complex bundle version history.
Incrementing of package version numbers without holes in the sequence
for each package, coupled with sub-minor releases of the bundle will
lead to a converging version history that IMHO will be easier to
understand and track (its hard enough for a OSGi newbee as it is)
Only when one of the packages ups its version to 1.3 does the bundle
move to v1.3.0
Did that make sense ?
Ian
Re: Version Numbers
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Tue, Nov 17, 2009 at 3:45 PM, Vidar Ramdal <vi...@idium.no> wrote:
> ...Running two different schemes - one for Sling API, and one for the
> other bundles - could easily add to the confusion, I suspect....
Not necessarily IMHO...the API and implementation bundles are slightly
different beasts.
-Bertrand
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Bertrand Delacretaz schrieb:
> On Tue, Nov 17, 2009 at 9:01 PM, Felix Meschberger <fm...@gmail.com> wrote:
>> Vidar Ramdal schrieb:
>>> ...Testing sounds good, but what do we do after the "test period" - if
>>> the test is successful, do we use this versioning scheme on all
>>> bundles?
>> Yes, but we will not modify all bundles right away. Rather I would say
>> we modify bundles as we are ready to release them and there is a
>> modification underway anyway....
>
> I would like us to vote on this, before we go any further than the api
> bundle experiment that we seem to agree on based on this thread.
>
> The impact of this change in version numbers management is high enough
> to warrant a formal vote, IMHO.
Makes sense. Also because I named this thing a "Version Policy", it
implies a vote will be held. For now I added a comment to indicate, this
is just a proposal.
Regards
Felix
Re: Version Numbers
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Tue, Nov 17, 2009 at 9:01 PM, Felix Meschberger <fm...@gmail.com> wrote:
> Vidar Ramdal schrieb:
>> ...Testing sounds good, but what do we do after the "test period" - if
>> the test is successful, do we use this versioning scheme on all
>> bundles?
>
> Yes, but we will not modify all bundles right away. Rather I would say
> we modify bundles as we are ready to release them and there is a
> modification underway anyway....
I would like us to vote on this, before we go any further than the api
bundle experiment that we seem to agree on based on this thread.
The impact of this change in version numbers management is high enough
to warrant a formal vote, IMHO.
-Bertrand
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Vidar Ramdal schrieb:
> On Tue, Nov 17, 2009 at 1:48 PM, Alexander Klimetschek <ak...@day.com> wrote:
>> That sounds good to me. That way one could ignore the package versions
>> if he likes to (I know you shouldn't, but it's more natural for people
>> new to osgi).
>>
>> +1 for "testing it" with the sling api bundle.
>
> Testing sounds good, but what do we do after the "test period" - if
> the test is successful, do we use this versioning scheme on all
> bundles?
Yes, but we will not modify all bundles right away. Rather I would say
we modify bundles as we are ready to release them and there is a
modification underway anyway.
For example: Bundle1 exports bp1 and has inner classes. Bundle1 is ready
for release, but there were no changes in bp1. So we set the export
version of bp1 to the previous version of Bundle1 and increase the
version of Bundle1 for the imminent release.
> Running two different schemes - one for Sling API, and one for the
> other bundles - could easily add to the confusion, I suspect.
No, running two schemes is wrong. Of course there is a transition
period, where bundles have not yet been adapted. But over time, this
situation will change and all bundles should adhere to the same scheme.
Regards
Felix
Re: Version Numbers
Posted by Vidar Ramdal <vi...@idium.no>.
On Tue, Nov 17, 2009 at 1:48 PM, Alexander Klimetschek <ak...@day.com> wrote:
> That sounds good to me. That way one could ignore the package versions
> if he likes to (I know you shouldn't, but it's more natural for people
> new to osgi).
>
> +1 for "testing it" with the sling api bundle.
Testing sounds good, but what do we do after the "test period" - if
the test is successful, do we use this versioning scheme on all
bundles?
Running two different schemes - one for Sling API, and one for the
other bundles - could easily add to the confusion, I suspect.
--
Vidar S. Ramdal <vi...@idium.no> - http://www.idium.no
Sommerrogata 13-15, N-0255 Oslo, Norway
+ 47 22 00 84 00 / +47 21 531941, ext 2070
Re: Version Numbers
Posted by Alexander Klimetschek <ak...@day.com>.
On Tue, Nov 17, 2009 at 13:28, Felix Meschberger <fm...@gmail.com> wrote:
> Hi,
>
> Bertrand Delacretaz schrieb:
>> On Tue, Nov 17, 2009 at 1:17 PM, Felix Meschberger <fm...@gmail.com> wrote:
>>> ...How about this:
>>>
>>> * The bundle version number is always >= the highest version
>>> number of all exported packages.
>>> * If only implementation fixes apply to a bundle, the micro
>>> number is increased
>>> * If the version number is to be incresed it is set to the next
>>> minor version number of the bundle....
>>>
>>> ...* Extend package1 API, thus:
>>> version 1.1.0
>>> exports package1,version 1.1
>>> exports package2,version 1.0
>>> contains implementation code
>>>
>>> * Extend package2 API, thus:
>>> version 1.2.0
>>> exports package1,version 1.1
>>> exports package2,version 1.2
>>> contains implementation code...
>>
>> And now, if package1's API changes (version 1.2), what's the bundle
>> version number?
>
> no, version 1.3
>
>>
>> I'd suggest 1.3.0, i.e. bump up the middle number whenever a package
>> version changes.
>
> Exactly, because package1 becomes 1.3
>
> (middle number == minor version number)
That sounds good to me. That way one could ignore the package versions
if he likes to (I know you shouldn't, but it's more natural for people
new to osgi).
+1 for "testing it" with the sling api bundle.
Regards,
Alex
--
Alexander Klimetschek
alexander.klimetschek@day.com
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Bertrand Delacretaz schrieb:
> On Tue, Nov 17, 2009 at 1:17 PM, Felix Meschberger <fm...@gmail.com> wrote:
>> ...How about this:
>>
>> * The bundle version number is always >= the highest version
>> number of all exported packages.
>> * If only implementation fixes apply to a bundle, the micro
>> number is increased
>> * If the version number is to be incresed it is set to the next
>> minor version number of the bundle....
>>
>> ...* Extend package1 API, thus:
>> version 1.1.0
>> exports package1,version 1.1
>> exports package2,version 1.0
>> contains implementation code
>>
>> * Extend package2 API, thus:
>> version 1.2.0
>> exports package1,version 1.1
>> exports package2,version 1.2
>> contains implementation code...
>
> And now, if package1's API changes (version 1.2), what's the bundle
> version number?
no, version 1.3
>
> I'd suggest 1.3.0, i.e. bump up the middle number whenever a package
> version changes.
Exactly, because package1 becomes 1.3
(middle number == minor version number)
Regards
Felix
>
> -Bertrand
>
Re: Version Numbers
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Tue, Nov 17, 2009 at 1:17 PM, Felix Meschberger <fm...@gmail.com> wrote:
> ...How about this:
>
> * The bundle version number is always >= the highest version
> number of all exported packages.
> * If only implementation fixes apply to a bundle, the micro
> number is increased
> * If the version number is to be incresed it is set to the next
> minor version number of the bundle....
>
> ...* Extend package1 API, thus:
> version 1.1.0
> exports package1,version 1.1
> exports package2,version 1.0
> contains implementation code
>
> * Extend package2 API, thus:
> version 1.2.0
> exports package1,version 1.1
> exports package2,version 1.2
> contains implementation code...
And now, if package1's API changes (version 1.2), what's the bundle
version number?
I'd suggest 1.3.0, i.e. bump up the middle number whenever a package
version changes.
-Bertrand
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Carsten Ziegeler schrieb:
> Felix Meschberger wrote:
>> Granted, it is not simple and easy, but it is definitely worth the effort.
> Ok, so if we would do this, we would use different versions for packages
> and the bundle version is then just the highest version number used for one
> package (at least in most cases).
> The only problem I still have is that in the end there is no correlation
> between the bundle version and the package versions. If for example a
> bundle has two packages A and B, we start with version 0.1 for both
> packages -> bundle version 0.1; then we change B to 0.2 -> bundle
> version 0.2 but A is still 0.1.
> Now we change A to 0.2 as well which would result in what bundle
> version? 0.2.2?
How about this:
* The bundle version number is always >= the highest version
number of all exported packages.
* If only implementation fixes apply to a bundle, the micro
number is increased
* If the version number is to be incresed it is set to the next
minor version number of the bundle.
Example:
* Initial revision of Bundle A
version 1.0.0
exports package1,version 1.0
exports package2,version 1.0
contains implementation code
* Fix implementation. thus:
version 1.0.1
exports package1,version 1.0
exports package2,version 1.0
contains implementation code
* Extend package1 API, thus:
version 1.1.0
exports package1,version 1.1
exports package2,version 1.0
contains implementation code
* Extend package2 API, thus:
version 1.2.0
exports package1,version 1.1
exports package2,version 1.2
contains implementation code
Note, there will not be a package2 version 1.1 but the version numbers
remain aligned and the version numbers always increase and there is at
least some coherence between package export and bundle version.
WDYT ?
Regards
Felix
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Carsten Ziegeler schrieb:
> Felix Meschberger wrote:
>> Yes, it is true: a bundle is *just* a deployment unit (and development
>> unit if you wish). Nothing more nothing less. Whether a package is part
>> of one bundle or another does not matter at all. As such the increased
>> version number of a bundle just indicates: hey there are some changes in
>> this bundle with respect to the previous version.
>>
>> Now, the level granularity of interaction between bundles *is* the
>> package: bundles don't care for other bundles; they care for packages to
>> wire to. And it is the package we are importing and exporting. As such
>> we have to assign version numbes on the correct level.
> Yes, right.
>
>> <SNIP/>
>> If I change the API in the o.a.s.api.resource package, why would it make
>> sense and make lives easier, if I upgrade the minor version number of
>> the package o.a.s.api.request, too ? In fact, this makes life even
>> harder for the end user: We have to upgrade the bundling implementing
>> the request interface (if only to increase package import version) and
>> we have to deploy the new bundle. Why ? Because the resource API was
>> upgraded. Does not make any sense at all. This is not what OSGi is about.
> Yes, sure, but I think this is more theory than practice. How likely is
> it that the there are two separate implementations, one for the resource
> and one for the request package? Only in this case, having different
> version numbers matters.
> Now, I as I said, having version numbers on a per package base seems to
> be more correct.
Point is that there is an API bundle whose API is implemented by more
than one implementation bundle: The Sling API exports API implemented by
the jcr/resource, the engine, scripting/core, servlet/resolver, and
possibly more bundles.
IIRC this is in fact the only such case in Sling.
>
>> So lets make life harder for the us working on the exported API ! The
>> harder this life, the harder we will think about changing the API !
>> Consider this as sort of an additional security net against too
>> deliberate API changes ....
>>
>> So whenever you change something in an exported package, make sure you
>> also think about consequences for your downstream user's in terms of
>> assigning the correct version number.
> Ok.
>
>> Yes, it requires more thinking. Yes, it requires more work on our side.
>> Yes, it might be error prone. But also, it is a problem of us coders
>> thus helping our users. Don't place the burden on our users. This is
>> IMHO the wrongest thing we could do.
>>
>> Finally: We should change a version number only if there is in fact a
>> change.
>>
>> Granted, it is not simple and easy, but it is definitely worth the effort.
> Ok, so if we would do this, we would use different versions for packages
> and the bundle version is then just the highest version number used for one
> package (at least in most cases).
> The only problem I still have is that in the end there is no correlation
> between the bundle version and the package versions. If for example a
> bundle has two packages A and B, we start with version 0.1 for both
> packages -> bundle version 0.1; then we change B to 0.2 -> bundle
> version 0.2 but A is still 0.1.
> Now we change A to 0.2 as well which would result in what bundle
> version? 0.2.2?
> Now this is no problem per se, it just makes the users life a little bit
> harder. Imagine you search for a bundle providing package A in version
> 0.2 - due to the package name/bundle symbol name correlation you choose
> the above bundle in version 0.2 - but that one does not contain it.
> So a better way would be to just increase a number for bundle release,
> like API R1, API R2 etc :)
Well, this is the same issue as for the OSGi API libraries: These (core
and compendium) are at version 4.2 while the packages "exported" are at
version 1.x.
> Again, with proper tooling all of this is no problem.
My stance is: tooling helps -- but it should not be a prerequisite.
>
> But maybe we should give it a try and see how it works.
Yep. Lets start with the proposed changes for SLING-1176 ;-)
Regards
Felix
Re: Version Numbers
Posted by Carsten Ziegeler <cz...@apache.org>.
Felix Meschberger wrote:
> Yes, it is true: a bundle is *just* a deployment unit (and development
> unit if you wish). Nothing more nothing less. Whether a package is part
> of one bundle or another does not matter at all. As such the increased
> version number of a bundle just indicates: hey there are some changes in
> this bundle with respect to the previous version.
>
> Now, the level granularity of interaction between bundles *is* the
> package: bundles don't care for other bundles; they care for packages to
> wire to. And it is the package we are importing and exporting. As such
> we have to assign version numbes on the correct level.
Yes, right.
> <SNIP/>
> If I change the API in the o.a.s.api.resource package, why would it make
> sense and make lives easier, if I upgrade the minor version number of
> the package o.a.s.api.request, too ? In fact, this makes life even
> harder for the end user: We have to upgrade the bundling implementing
> the request interface (if only to increase package import version) and
> we have to deploy the new bundle. Why ? Because the resource API was
> upgraded. Does not make any sense at all. This is not what OSGi is about.
Yes, sure, but I think this is more theory than practice. How likely is
it that the there are two separate implementations, one for the resource
and one for the request package? Only in this case, having different
version numbers matters.
Now, I as I said, having version numbers on a per package base seems to
be more correct.
> So lets make life harder for the us working on the exported API ! The
> harder this life, the harder we will think about changing the API !
> Consider this as sort of an additional security net against too
> deliberate API changes ....
>
> So whenever you change something in an exported package, make sure you
> also think about consequences for your downstream user's in terms of
> assigning the correct version number.
Ok.
>
> Yes, it requires more thinking. Yes, it requires more work on our side.
> Yes, it might be error prone. But also, it is a problem of us coders
> thus helping our users. Don't place the burden on our users. This is
> IMHO the wrongest thing we could do.
>
> Finally: We should change a version number only if there is in fact a
> change.
>
> Granted, it is not simple and easy, but it is definitely worth the effort.
Ok, so if we would do this, we would use different versions for packages
and the bundle version is then just the highest version number used for one
package (at least in most cases).
The only problem I still have is that in the end there is no correlation
between the bundle version and the package versions. If for example a
bundle has two packages A and B, we start with version 0.1 for both
packages -> bundle version 0.1; then we change B to 0.2 -> bundle
version 0.2 but A is still 0.1.
Now we change A to 0.2 as well which would result in what bundle
version? 0.2.2?
Now this is no problem per se, it just makes the users life a little bit
harder. Imagine you search for a bundle providing package A in version
0.2 - due to the package name/bundle symbol name correlation you choose
the above bundle in version 0.2 - but that one does not contain it.
So a better way would be to just increase a number for bundle release,
like API R1, API R2 etc :)
Again, with proper tooling all of this is no problem.
But maybe we should give it a try and see how it works.
Carsten
--
Carsten Ziegeler
cziegeler@apache.org
Re: Version Numbers
Posted by Karl Pauls <ka...@gmail.com>.
On Tue, Nov 17, 2009 at 9:51 AM, Vidar Ramdal <vi...@idium.no> wrote:
> On Tue, Nov 17, 2009 at 8:34 AM, Felix Meschberger <fm...@gmail.com> wrote:
>
>> [...]
>> If I change the API in the o.a.s.api.resource package, why would it make
>> sense and make lives easier, if I upgrade the minor version number of
>> the package o.a.s.api.request, too ? In fact, this makes life even
>> harder for the end user: We have to upgrade the bundling implementing
>> the request interface (if only to increase package import version) and
>> we have to deploy the new bundle. Why ? Because the resource API was
>> upgraded. Does not make any sense at all. This is not what OSGi is about.
>
> OK, but how often does that happen?
> If a package is developed independently of other packages in the same
> bundle, it sounds to me as if the package should be a bundle of its
> own right?
A bundle is just a deployment unit - one can mix and match packages in
a bundle as one sees fit. This boils down to the difference between
Require-Bundle and Import-Package. In case of the former, I agree,
versioning packages isn't that important but in the latter case, it
is. However, I think there is another divider line which might be more
interesting to look at namely, api v.s. implementation packages.
In case of an api package it makes a lot of sense to version it
independently along the lines of what Felix was suggesting. In case of
implementation packages it might not be that important as they might
change a lot and one would probably want a tighter coupling anyways --
hence, why not do the following:
version api packages independently along the line of what Felix is suggesting
version implementation packages based on the bundle version (and
possibly make importers be hard coupled by using the symbolic-name
requirement).
I guess this is pretty much what Bertrand was suggesting too? However,
regarding the burden on the user, notice, bnd will look for the
package version when it generates the Import-Package clause so
assuming the users use bnd or the maven-bundle-plugin then it
shouldn't be that much of a problem for them as bnd can do the correct
thing for them already as long as they tell it to do so via a
versionpolicy of
[${version;==;${@}},${version;=+;${@}}) for implementors as it
creates e.g.: [1.2,1.3)
[${version;==;${@}},${version;+;${@}}) for users as it creates e.g.: [1.2,2)
regards,
Karl
> --
> Vidar S. Ramdal <vi...@idium.no> - http://www.idium.no
> Sommerrogata 13-15, N-0255 Oslo, Norway
> + 47 22 00 84 00 / +47 21 531941, ext 2070
>
--
Karl Pauls
karlpauls@gmail.com
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Vidar Ramdal schrieb:
> On Tue, Nov 17, 2009 at 8:34 AM, Felix Meschberger <fm...@gmail.com> wrote:
>
>> [...]
>> If I change the API in the o.a.s.api.resource package, why would it make
>> sense and make lives easier, if I upgrade the minor version number of
>> the package o.a.s.api.request, too ? In fact, this makes life even
>> harder for the end user: We have to upgrade the bundling implementing
>> the request interface (if only to increase package import version) and
>> we have to deploy the new bundle. Why ? Because the resource API was
>> upgraded. Does not make any sense at all. This is not what OSGi is about.
>
> OK, but how often does that happen?
> If a package is developed independently of other packages in the same
> bundle, it sounds to me as if the package should be a bundle of its
> own right?
>
It depends ;-)
Really, this does not happen very often and in fact, we have one bundle
IIRC which is the main "culprit" of this discussion: The Sling API bundle.
All other bundles have rather "complete" exports in that they export API
for implementations contained in the same bundle. And most of these
bundles export a single package anyway, so there is not much of a deal
either -- except that we might want to replace the
"version=${pom.version}" statement by an explicit version number
assignment to prevent export version increase on bundle version increase.
This bundle contains packages which evolve independently of each other
but to make it easier for deployment (and development for that matter)
we merge these packages into a single bundle.
Regards
Felix
Re: Version Numbers
Posted by Vidar Ramdal <vi...@idium.no>.
On Tue, Nov 17, 2009 at 8:34 AM, Felix Meschberger <fm...@gmail.com> wrote:
> [...]
> If I change the API in the o.a.s.api.resource package, why would it make
> sense and make lives easier, if I upgrade the minor version number of
> the package o.a.s.api.request, too ? In fact, this makes life even
> harder for the end user: We have to upgrade the bundling implementing
> the request interface (if only to increase package import version) and
> we have to deploy the new bundle. Why ? Because the resource API was
> upgraded. Does not make any sense at all. This is not what OSGi is about.
OK, but how often does that happen?
If a package is developed independently of other packages in the same
bundle, it sounds to me as if the package should be a bundle of its
own right?
--
Vidar S. Ramdal <vi...@idium.no> - http://www.idium.no
Sommerrogata 13-15, N-0255 Oslo, Norway
+ 47 22 00 84 00 / +47 21 531941, ext 2070
Re: Version Numbers
Posted by Felix Meschberger <fm...@gmail.com>.
Hi,
Carsten Ziegeler schrieb:
> Hi,
>
> it seems that this is a complicated topic; as there has been no reply so
> far, I'll give it a try :)
Yes, it is -- to a certain extent ;-)
>
> First, I agree with most of what you wrote below :)
>
> But :) while I see that it makes sense to specify versions on a per
> package base, I'm not sure if this is worth it. If you specify the
> version per package you have the least disruptive and most compatible
> behaviour and it is no problem for OSGi (or any other tooling) to wire
> everything correctly together.
> But I fear that this is too complicated for us humans :) (at least it is
> for me...) - we have this nice notion of a module (aka bundle), which
> has a version - now although the OSGi spec does not mandate that the
> exported package inside a bundle have the same version as the bundle
> itself, it seems to be the most natural way for me. Otherwise the notion
> of a bundle becomes less important as it is just a deployment unit (more
> or less).
> So when I see an API bundle with version 2.1 I expect that the exported
> packages have version 2.1 as well - sure my expectation could be wrong,
> but that's how I would read it today (even when knowing all the problems
> you mention).
> We could end up with bundle version 2.9 while just one package inside
> has version 2.9 and others still have 2.0 - again, that's not a problem
> by itself, it seems to be more correct and OSGi has no problems with it.
> But users might have.
>
> So I'm a little bit reluctant in this case.
Yes, it is true: a bundle is *just* a deployment unit (and development
unit if you wish). Nothing more nothing less. Whether a package is part
of one bundle or another does not matter at all. As such the increased
version number of a bundle just indicates: hey there are some changes in
this bundle with respect to the previous version.
Now, the level granularity of interaction between bundles *is* the
package: bundles don't care for other bundles; they care for packages to
wire to. And it is the package we are importing and exporting. As such
we have to assign version numbes on the correct level.
Consider this: If we agree on the semantics for version numbers of
exported packages:
* major number change: incompatible API
* minor number change: extended but compatible API
(implementations need to be modified, users run unmodified)
* micro number change: no API change at all
(no changes needed, such updates may be JavaDoc or some
implementation fixes in exported packages)
So now we have a bundle exporting two packages with interfaces (the
Sling API comes to mind), say o.a.s.api.resource and o.a.s.api.request.
The interfaces of both packages are implemented by other bundles
importing from the API bundle.
If I change the API in the o.a.s.api.resource package, why would it make
sense and make lives easier, if I upgrade the minor version number of
the package o.a.s.api.request, too ? In fact, this makes life even
harder for the end user: We have to upgrade the bundling implementing
the request interface (if only to increase package import version) and
we have to deploy the new bundle. Why ? Because the resource API was
upgraded. Does not make any sense at all. This is not what OSGi is about.
So lets make life harder for the us working on the exported API ! The
harder this life, the harder we will think about changing the API !
Consider this as sort of an additional security net against too
deliberate API changes ....
So whenever you change something in an exported package, make sure you
also think about consequences for your downstream user's in terms of
assigning the correct version number.
Yes, it requires more thinking. Yes, it requires more work on our side.
Yes, it might be error prone. But also, it is a problem of us coders
thus helping our users. Don't place the burden on our users. This is
IMHO the wrongest thing we could do.
Finally: We should change a version number only if there is in fact a
change.
Granted, it is not simple and easy, but it is definitely worth the effort.
Regards
Felix
>
> Carsten
>
> Felix Meschberger wrote:
>> Hi all,
>>
>> <warning>lengthy mail</warning>
>>
>> In comments to SLING-1176 Ian Boston wrote:
>>
>> "The exports in bundle/api/pom.xml look like they might
>> become problematic from a support point of view, although
>> we probably cant avoid this.
>> [...]
>> [The problem is the] manual maintenance of the version numbers.
>> (not a big problem bit needs to be done)"
>>
>> I agree, that this is a problem. Let me reasonate on this a bit ;-)
>>
>> As a reference you might want to read my latest blog post at [1] and
>> also what the Eclipse guys have to say [2] (great read, btw).
>>
>> So for Sling, we have three kinds of version numbers: (1) Big Sling
>> releases, (2) Sling bundles, and (3) exported packages.
>>
>> For (1) we have already an ample solution in that we just increase the
>> number from release to release. Just remember that a "big Sling release"
>> is a convenience release of existing released Sling bundles.
>>
>> For (2) version numbers are just defined as the <version> element of the
>> bundle's POM. The only restriction here is, that we decided to use even
>> numbers for releases and odd numbers for SNAPSHOTs. Whether and when
>> which version part is increased is not codified.
>>
>> For (3) the situation is more problematic since there are a number of
>> places to set exported package version number: In a packageinfo file
>> inside the package (picked up by the Bundle plugin to set the export
>> version) or explicitly in the <Export-Package> element of the Bundle
>> plugin configuration or by reference to the bundle version number using
>> the ${pom.version} variable.
>>
>> Upto now, we mostly used the ${pom.version} notation linking the
>> exported package version to the bundle version. This works well for
>> bundles with simple exports. For more complicated bundles, specifically
>> for bundles with multiple exported packages which may evolve
>> independently, this does not work well.
>>
>> Consider for example the Sling API bundle, which exports 7 packages.
>> Each of which may evolve independently. Now the resource package is
>> enhanced causing a minor version increase. Should the version numbers of
>> the other exports also be increased ? Thus acting as if there was some
>> API change ?
>>
>> I would say, no. Particularly if some API implementation bundle is
>> restricting the import version of the API implemented. Such an
>> implementation would immediately stop working because the version has
>> been increased. But since there has been no change, the implementation
>> would still be correct.
>>
>> So, I think, we should evolve the exported package versions
>> independently from each other and possibly even independently from the
>> bundle version.
>>
>> This places more burden on the developer when deciding on the exported
>> package version - in fact this requires such a decision as compared to
>> have Maven take the decision by just setting the bundle version.
>>
>> The only problem is: Where shall this be noted ? In the POM or in the
>> packageinfo file ? If we would place the packageinfo file just beneath
>> the class source files, I would say, in the packageinfo file.
>>
>> But this would require defining the class source locations as resource
>> location in the POM (at least for packageinfo) files.
>>
>> I am not sure ....
>>
>> WDYT ?
>>
>> Regards
>> Felix
>>
>> [1] http://blog.meschberger.ch/2009/10/on-version-numbers.html
>> [2] http://wiki.eclipse.org/index.php/Version_Numbering
>>
>
>
Re: Version Numbers
Posted by Carsten Ziegeler <cz...@apache.org>.
Hi,
it seems that this is a complicated topic; as there has been no reply so
far, I'll give it a try :)
First, I agree with most of what you wrote below :)
But :) while I see that it makes sense to specify versions on a per
package base, I'm not sure if this is worth it. If you specify the
version per package you have the least disruptive and most compatible
behaviour and it is no problem for OSGi (or any other tooling) to wire
everything correctly together.
But I fear that this is too complicated for us humans :) (at least it is
for me...) - we have this nice notion of a module (aka bundle), which
has a version - now although the OSGi spec does not mandate that the
exported package inside a bundle have the same version as the bundle
itself, it seems to be the most natural way for me. Otherwise the notion
of a bundle becomes less important as it is just a deployment unit (more
or less).
So when I see an API bundle with version 2.1 I expect that the exported
packages have version 2.1 as well - sure my expectation could be wrong,
but that's how I would read it today (even when knowing all the problems
you mention).
We could end up with bundle version 2.9 while just one package inside
has version 2.9 and others still have 2.0 - again, that's not a problem
by itself, it seems to be more correct and OSGi has no problems with it.
But users might have.
So I'm a little bit reluctant in this case.
Carsten
Felix Meschberger wrote:
> Hi all,
>
> <warning>lengthy mail</warning>
>
> In comments to SLING-1176 Ian Boston wrote:
>
> "The exports in bundle/api/pom.xml look like they might
> become problematic from a support point of view, although
> we probably cant avoid this.
> [...]
> [The problem is the] manual maintenance of the version numbers.
> (not a big problem bit needs to be done)"
>
> I agree, that this is a problem. Let me reasonate on this a bit ;-)
>
> As a reference you might want to read my latest blog post at [1] and
> also what the Eclipse guys have to say [2] (great read, btw).
>
> So for Sling, we have three kinds of version numbers: (1) Big Sling
> releases, (2) Sling bundles, and (3) exported packages.
>
> For (1) we have already an ample solution in that we just increase the
> number from release to release. Just remember that a "big Sling release"
> is a convenience release of existing released Sling bundles.
>
> For (2) version numbers are just defined as the <version> element of the
> bundle's POM. The only restriction here is, that we decided to use even
> numbers for releases and odd numbers for SNAPSHOTs. Whether and when
> which version part is increased is not codified.
>
> For (3) the situation is more problematic since there are a number of
> places to set exported package version number: In a packageinfo file
> inside the package (picked up by the Bundle plugin to set the export
> version) or explicitly in the <Export-Package> element of the Bundle
> plugin configuration or by reference to the bundle version number using
> the ${pom.version} variable.
>
> Upto now, we mostly used the ${pom.version} notation linking the
> exported package version to the bundle version. This works well for
> bundles with simple exports. For more complicated bundles, specifically
> for bundles with multiple exported packages which may evolve
> independently, this does not work well.
>
> Consider for example the Sling API bundle, which exports 7 packages.
> Each of which may evolve independently. Now the resource package is
> enhanced causing a minor version increase. Should the version numbers of
> the other exports also be increased ? Thus acting as if there was some
> API change ?
>
> I would say, no. Particularly if some API implementation bundle is
> restricting the import version of the API implemented. Such an
> implementation would immediately stop working because the version has
> been increased. But since there has been no change, the implementation
> would still be correct.
>
> So, I think, we should evolve the exported package versions
> independently from each other and possibly even independently from the
> bundle version.
>
> This places more burden on the developer when deciding on the exported
> package version - in fact this requires such a decision as compared to
> have Maven take the decision by just setting the bundle version.
>
> The only problem is: Where shall this be noted ? In the POM or in the
> packageinfo file ? If we would place the packageinfo file just beneath
> the class source files, I would say, in the packageinfo file.
>
> But this would require defining the class source locations as resource
> location in the POM (at least for packageinfo) files.
>
> I am not sure ....
>
> WDYT ?
>
> Regards
> Felix
>
> [1] http://blog.meschberger.ch/2009/10/on-version-numbers.html
> [2] http://wiki.eclipse.org/index.php/Version_Numbering
>
--
Carsten Ziegeler
cziegeler@apache.org