Re: [cross-project-issues-dev] Specifying version requirements -- let's

[David M Williams <david_williams@xxxxxxxxxx>]

Thanks, Pascal. Very helpful. 

Projects, 

who has not yet implemented version
constraints on plugin pre-reqs for RC5? who has no plans to for the Callisto
release? 

Raising your hand for the second question
is no good, but .. if you raised your hand for the first one, here is some
additional help for you (possibly). 

I "beefed up" Pascal's original
tool, so it gives more "manfest-like" ouput. And it allows a
"conservative" range to be produced, if anyone prefers that.


I sincerely hope none of you have 130
plugins to fix up like I did, 
but, as I did them, I _promised_ my
PMC that _everyone_ was doing this ... so, 
don't make a liar out of me, please.


Still need help via a tool? 

I've put the source for my could-almost-be-a-PDE
patch :) in /cvsroot/callisto, see
org.eclipse.callisto.tools.versionchecker

And, for me, it was much more helpful
to actually re-write the manifest.mf files .. or, if you only have 20-40
plugins, at least this version gives you a 
"paste-able" version of what
should be in your manifest.mf files.  Plus, my version maintains any
"optional" or "visibility" attributes you may have

set, so makes the changes a little less
traumatic.

So, if you like tools, try it out, if
not, please fix up by RC5 anyway, or let us all know here on this list
you will not be able to (and why, etc.). 

I know for some this may seem like a
"new requirement", but its not really ... it just may have been
lost in our 
"four-field version number"
discussions we had in the beginning (and everyone agreed to).

So, really, is anyone planning on NOT
providing range constraints for Callisto release?  Raise you hands
higher please ... since I don't see any, I'll assume eveyone is  :)


Thanks all, 



= = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = 

For your reading pleasure .. I've actually
provided some javadoc for the tool .. and even spell checked it. If you
have improvements to make, please contribute them back .. and, who knows
... maybe someone will provide a PDE patch for the "clean up manifests"
function! 
= = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = = = = = = = = = = = 


A simple, unsupported, little-tested utility to help convert
from using unconstrained pre-req'd bundles, to ones constrained to be within
a certain range. For example, if a plugin's manifest.mf file specifies

Require-Bundle: org.eclipse.core.runtime

this utility will write

Require-Bundle: org.eclipse.core.runtime;bundle-version="[3.2.0,4.0.0)"

or

Require-Bundle: org.eclipse.core.runtime;bundle-version="[3.2.0,3.3.0)"

if -conservative is specified. In all case the lower bound is determined by the version found as this utility actually runs.

Directives:

-filter "some regx _expression_"

Will write/check manifest only for those plugins matching regx _expression_.

-conservative

Will increment 'minor' code, instead of 'major' code in upper bound of the range. This is required for those using another plugin's internal (non-API) methods, and recommended if you do not know for sure you are using API-only. The default is not-conservative, which increments the major field.

-workspaceRoot "absolute file system path name to workspace"

If specified, the manifest.mf files found in the workspace will be re-written with the results of this tool (maintaining as-is the lines not in the "Requires-Bundle" section. Note. The workspace must "match" the runtime the tool is running in, for this operation to make any sense. The default behavior is to only write the recommended "Require-Bundle:" section to the the console log, which you can check, fix up, and paste into your manifest.mf file as you like.

Note: re-export visibility and optional resolution are maintained "as is" in output, but other pre-req settings (e.g. vendor?) may be lost. The intent is to provide "ready for pasting" content for the often used cases.

Example invocation:

 
java -jar startup.jar -clean -application org.eclipse.callisto.tools.versionchecker.dependencyChecker

Example output:

 bundle org.eclipse.wst.xml.core
Require-Bundle:
org.eclipse.core.runtime;bundle-version="[3.2.0,3.3.0)",
org.eclipse.core.resources;bundle-version="[3.2.0,3.3.0)",
org.eclipse.wst.common.uriresolver;bundle-version="[1.1.0,1.2.0)",
org.eclipse.wst.sse.core;bundle-version="[1.1.0,1.2.0)",
org.eclipse.text;bundle-version="[3.2.0,3.3.0)",
org.eclipse.jem.util;resolution:=optional;bundle-version="[1.2.0,1.3.0)",
org.eclipse.wst.validation;bundle-version="[1.1.0,1.2.0)",
org.eclipse.emf.ecore.edit;resolution:=optional;bundle-version="[2.2.0,2.3.0)",
org.eclipse.wst.common.emf;resolution:=optional;bundle-version="[1.1.0,1.2.0)",
org.eclipse.emf.ecore.xmi;resolution:=optional;bundle-version="[2.2.0,2.3.0)",
org.eclipse.wst.common.emfworkbench.integration;resolution:=optional;bundle-version="[1.1.0,1.2.0)",
org.eclipse.wst.common.core;bundle-version="[1.1.0,1.2.0)",
com.ibm.icu;bundle-version="[3.4.4,3.5.0)",
org.apache.xerces;visibility:=reexport;bundle-version="[2.8.0,2.9.0)"

Pascal Rapicault <Pascal_Rapicault@xxxxxxxxxx>
Sent by: cross-project-issues-dev-bounces@xxxxxxxxxxx

06/12/2006 02:07 PM

Please respond to
Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>

To	cross-project-issues-dev@xxxxxxxxxxx
cc	Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>, cross-project-issues-dev-bounces@xxxxxxxxxxx
Subject	Re: [cross-project-issues-dev] Specifying version requirements

When no constraints are specified, it means that the plug-in can work against
any version of the required plug-ins (for example, EMF 2.2 should be able
to run against eclipse 1.0 state that it will run against all the version
of eclipse that will come in the future :-)) which of course is not true
because of API changes, usage of internals, etc.... For the end user it
means that he/she can install a plug-in run it and get random exceptions
(NoClassDefFound, NoSuchMethod, etc,)  or unexpected behavior when
the plug-in was just simply not meant to run and shoud have not resolved
is the first place. 
Of course one might say: "this won't happen for callisto since we
are all shipping on the same date".  This is true but callisto
is only one instant in time and as projects starts shipping point releases
on their own schedule, then the user problem I was outlining previously
will occur and the remedy to this will be another synchronize release which
will be somehow acknowledging that our APIs are not real, and we can't
do components. 

So the benefits are (in random order): being able to detect incompatibilities
sooner than later, increase modularity by making it easier for people to
compose individual pieces, not longer require one big sync'ed release,
show that we understand components, force API to be stable and push the
creation of new APIs,etc... 

So how to do it: 
- run the tool I sent earlier this month 
- for each unsatisfied constraint review the range given and adjust the
proposed value depending on the following cases: 
        - if you use only api from the required plug-in,
then specify a range from the current version up to the next major (for
example [3.2.0, 4.0.0)). This will guarantee that this constraint will
be satisfied as long as the required plug-in does not make a breaking api
change. 
        - if you rely on a particular bug fix, then
specify a range from the specific version containing the fix up to the
next major (for example [3.1.3, 4.0.0)). 
        - if you use some internals, then specify a
range from the specific version number up to the next minor excluded (for
example [3.2.0, 3.3.0)). Basically here we are trying to be as conservative
as possible while still leaving space for the required plug-in to do bug
fix. Of course here there can be cases where the internal has been changed
in the point release, but restricting ourselves to just one precise version
would just be too cumbersome. Also note that when specifying such a range
 you need to enter a bug report requesting for new API so that
this situation does not occur again in the future.

HTH, 

PaScaL

David M Williams <david_williams@xxxxxxxxxx>
Sent by: cross-project-issues-dev-bounces@xxxxxxxxxxx

06/12/2006 01:11 PM

Please respond to
Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>

To	Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>
cc
Subject	Re: [cross-project-issues-dev] Specifying version requirements

Pascal, or others who might know .... 

What is the effect of not specifying these constraints? Does it default
to "any" .... so, the danger is its just defined too broadly?
Picking the highest available at runtime? Leading to a danger of hard to
maintain install bases? Or, is it something even worse? (such as. "randomly
picks all from possibilities each time its ran"?) 

Thanks,

David M Williams/Raleigh/IBM@IBMUS
Sent by: cross-project-issues-dev-bounces@xxxxxxxxxxx

05/31/2006 03:25 PM

Please respond to
Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>

To	Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>
cc
Subject	Re: [cross-project-issues-dev] Specifying version requirements

Pascal. This looks like a very helpful tool and I plan to use it soon myself.

Might I request .. can it and the source be attached to a bugzilla? Or
... is it already in CVS somewhere? You know I trust you  :)  but
as a matter of policy I hate to execute "class" files from a
mailing list, especially without source. 

Another advantage of a bugzilla is then people  could suggest, or
contribute back, feature enhancements. For example, I'd possibly like a
version that gives the "conservative" range instead of the "api
range". 



And, will even suggest the reasons for it here ... for public scrutiny.
 In WTP at least, I think we use enough non-API (mostly within ourselves,
not too much from base or pre-reqs) that I'd like to do a "mass update"
that used the conservative range. Then component owners (those with more
knowledge of the code) could "open it up" if they know for sure
they do not use any non-API, or otherwise untrustworthy code. 

I think the conservative approach is safest, as we get used to this new
versioning, since, as I see it, the cost of making an error is worse if
give to wide a range. 
      Cost if too wide: clients could end up "broken"
and have to wait for fixed version, get the fixed version, might even have
to uninstall and re-install everything, with fixed version, to get working
again. 
      Cost of too narrow: an update might have to be provided
that was not technically really necessary, just to bump up a version number
range. 


Any comments/suggestions?

Pascal Rapicault <Pascal_Rapicault@xxxxxxxxxx>
Sent by: cross-project-issues-dev-bounces@xxxxxxxxxxx

05/29/2006 02:32 PM

Please respond to
Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>

To	cross-project-issues-dev@xxxxxxxxxxx
cc
Subject	[cross-project-issues-dev] Specifying version requirements

Hi all, 

Earlier this year, the eclipse team put together guidelines on how to version
plug-ins: http://www.eclipse.org/equinox/documents/plugin-versioning.html.
These guidelines have been adopted by a lot of the callisto teams, however
most of them (including the SDK team) missed the fact that specifying properly
its version was only part of the problem and that it was equivalently important
to specify ranges when requiring plug-ins. 

Therefore, in order to help all of you specify the ranges on all the required
plug-ins on time for callisto, I have written a little plug-in that will
propose values for all the missing ranges. The generated values assume
that you are only using APIs however if you know otherwise you should specify
a tighter range by lowering the value for the upper bound.
Example of an output: 
bundle org.eclipse.cdt.ui              
                 <---------
plug-in name which has the problem 
     org.eclipse.ui.ide;bundle-version="[3.2.0,4.0.0)"
       <--------- proposed value
     org.eclipse.ui.views;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.jface.text;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.ui.workbench.texteditor;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.ui.editors;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.ui;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.core.resources;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.search;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.compare;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.cdt.core;bundle-version="[3.1.0,4.0.0)"
     org.eclipse.ui.console;bundle-version="[3.1.100,4.0.0)"
     org.eclipse.core.filebuffers;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.core.runtime;bundle-version="[3.2.0,4.0.0)"
     org.eclipse.help;bundle-version="[3.2.0,4.0.0)"

How to use the tool: 
- copy the attached jar in your plugins folder 
- run the following command 
     java -jar startup.jar -clean -application org.eclipse.core.runtime.versionchecker.dependencyChecker

If you want to only check the dependency for a limited set of plugins,
you can specify the -filter option and specify a regexp matching the bundle
names. For example "-filter .*cdt.*" will only match the CDT
plug-ins. 

Regards, 

PaScaL 
[attachment "org.eclipse.core.runtime.versionchecker_1.0.0.jar"
deleted by David M Williams/Raleigh/IBM] _______________________________________________
cross-project-issues-dev mailing list
cross-project-issues-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
_______________________________________________
cross-project-issues-dev mailing list
cross-project-issues-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
_______________________________________________
cross-project-issues-dev mailing list
cross-project-issues-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
_______________________________________________
cross-project-issues-dev mailing list
cross-project-issues-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev