Re: [equinox-dev] .qualifier for export package?

[BJ Hargrave <hargrave@xxxxxxxxxx>]

If the new API is completely pull such
that the API is again the same as the last released version then yes, revert
to 1.0. But as long as the API is different than the last released version,
it should remain 1.1. Putting a qualifier of a build date or tag on the
package export is wrong. It will lead one to believe that importing that
package with a qualifier is ok and meaningful. But a qualifier of a build
date or tag says nothing about API backwards compatibility. It is just
a form of identity with no meaningful ordering.
--

BJ Hargrave Senior Technical Staff Member, IBM OSGi Fellow and CTO of the OSGi Alliance hargrave@xxxxxxxxxx

office: +1 386 848 1781 mobile: +1 386 848 3788

From:	Thomas Watson/Austin/IBM@IBMUS
To:	Equinox development mailing list <equinox-dev@xxxxxxxxxxx>
Date:	2008/09/05 12:03 PM
Subject:	Re: [equinox-dev] .qualifier for export package?

---

Anyone adopting early API (before API freeze) has to be
prepared for breaking changes. We must have the flexibility to develop
our new API and increment our versions properly from one final release
to the next. Imagine the following scenario

foo; version=1.0

The M1 build adds new backwards compatibility API to foo and the version
becomes:

foo; version=1.1

In the M2 build it is decided that the new API is bad and is pulled out,
now what do you think foo version should be? back to 1.0 or 1.2 or 2.0?
removing the API technically is a backwards compatibility change so technically
the version should become 2.0 when compared to the version of foo from
the M1 build. I think we must evolve our API versions from the last release,
not from build to build. In this case the foo package contains the exact
API as the 1.0 version, making it anything other than 1.0 is wrong and
confusing.

Adding a qualifier will allow clients to depend on a particular version
of the package from a particular build (or CVS tag) if they really need
to. But I do not think this is the common case and we should not recommend
as a best practice to include qualifiers in version ranges used in Import-Package
or Require-Bundle.

Tom

BJ
Hargrave---09/05/2008 09:40:56 AM---But the qualifier is just another component
of the version to allow ordering among versions. Why is change it any different
tha

From:	BJ Hargrave/Austin/IBM@IBMUS
To:	Equinox development mailing list <equinox-dev@xxxxxxxxxxx>
Date:	09/05/2008 09:40 AM
Subject:	Re: [equinox-dev] .qualifier for export package?

---

But the qualifier is just another component of the version to allow ordering
among versions. Why is change it any different than changing any other
component of the version? (Other than semantic we place on the version
components.) 

Changing any part of the version during development is only interesting
if someone will change their import to depend upon that "higher"
version. And if someone becomes dependent upon that new version, then making
backwards incompatible API changes during development is in trouble. Backing
out API changes made during dev does not mean you can simply revert the
version number since there may have been changes in other areas of the
package which are not affected by the back out. 

Original: 1.2 
Make change A: 1.2.0.qual1 
Make change B: 1.2.0.qual2 
Backout change A: 1.2.0.qual1 is not right since change B is still there.

--

BJ Hargrave Senior Technical Staff Member, IBM OSGi Fellow and CTO of the OSGi Alliance hargrave@xxxxxxxxxx

office: +1 386 848 1781 mobile: +1 386 848 3788

From:	Thomas Watson/Austin/IBM@IBMUS
To:	Equinox development mailing list <equinox-dev@xxxxxxxxxxx>
Date:	2008/09/05 10:11 AM
Subject:	Re: [equinox-dev] .qualifier for export package?

---

If we decided to back out an API then we revert the version back and have
to make the necessary announcements to the community to prepare them for
the version decrease in mid development cycle. From release to release
our version have to follow our version rules at http://wiki.eclipse.org/index.php/Version_Numbering

I do not think we should change the minor number each time API is added
for each I-Build or milestone. That should only be done once each release.
What Jeff would like is the ability to pick a particular build of a package
from a development. If this is important then the qualifier approach is
likely the most simple approach. Another approach could be to have exporters
add a matching attribute that indicates new API. But this does not scale
well. For example:

Export-Package: foo; version="2.1"; bar=true

This would be used when some new bar feature was added to the foo package,
then

Export-Package: foo; version="2.1"; bar=true; baz=true

This would be used when both the bar and baz features are added to the
foo package. This is possible but is hard to manage and is just ugly. Is
this a serious enough issue that we must address it? It seems like it is
just a temporary issue that goes away once the final release is done.

Tom

BJ
Hargrave---09/05/2008 07:50:25 AM---If I understand #2 correctly, then
you want a controlled version practice during the development cycle. This
is challenging sin

From:	BJ Hargrave/Austin/IBM@IBMUS
To:	Equinox development mailing list <equinox-dev@xxxxxxxxxxx>
Date:	09/05/2008 07:50 AM
Subject:	Re: [equinox-dev] .qualifier for export package?

---

If I understand #2 correctly, then you want a controlled version practice
during the development cycle. This is challenging since you may want to
change your mind and break from a previous API change made during the same
dev cycle. 

For example: 

1.2 is the last shipped version of a package (let's say thats in Ganymede).

So during the dev cycle you change to 1.3 because you add new API. Soon
you add more API. 1.3.1 or 1.4? Then you decide to pull some of those API
changes because we learned they did not work as expected. What version
then? 2.0? Because of the breaking change? I think this is a fairly impossible
situation during the dev cycle because we are free to change our mind about
new API until API freeze. 

I think the odd/even versioning could be useful. But it still does not
easily handle the removal of new API previously added during the dev cycle.
It only seems to work well if the API only "grows" but does not
shrink. 

--

BJ Hargrave Senior Technical Staff Member, IBM OSGi Fellow and CTO of the OSGi Alliance hargrave@xxxxxxxxxx

office: +1 386 848 1781 mobile: +1 386 848 3788

From:	Jeff McAffer <jeff@xxxxxxxxx>
To:	Equinox development mailing list <equinox-dev@xxxxxxxxxxx>
Date:	2008/09/05 04:32 AM
Subject:	Re: [equinox-dev] .qualifier for export package?

---

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 OSGi Fellow and CTO of the OSGi Alliance hargrave@xxxxxxxxxx

office: +1 386 848 1781 mobile: +1 386 848 3788

From:	Jeff McAffer <jeff@xxxxxxxxx>
To:	Equinox development mailing list <equinox-dev@xxxxxxxxxxx>
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 OSGi Fellow and CTO of the OSGi Alliance hargrave@xxxxxxxxxx

office: +1 386 848 1781 mobile: +1 386 848 3788

From:	Thomas Watson/Austin/IBM@IBMUS
To:	Equinox development mailing list <equinox-dev@xxxxxxxxxxx>
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

"Chris
Aniszczyk" ---08/31/2008 02:46:34 PM---On Sun, Aug 31, 2008 at 5:53
AM, Jeff McAffer < jeff@xxxxxxxxx

From:	"Chris Aniszczyk" <caniszczyk@xxxxxxxxx>
To:	"Equinox development mailing list" <equinox-dev@xxxxxxxxxxx>
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 <jeff@xxxxxxxxx>
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@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev

_______________________________________________
equinox-dev mailing list
equinox-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev

---

_______________________________________________
equinox-dev mailing list
equinox-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev

---

_______________________________________________
equinox-dev mailing list
equinox-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev

_______________________________________________
equinox-dev mailing list
equinox-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev
_______________________________________________
equinox-dev mailing list
equinox-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev

_______________________________________________
equinox-dev mailing list
equinox-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/equinox-dev