RE: [cdt-dev] Managed Build System Versioning Strategy

[Sean Evoy <sevoy@xxxxxxxxxx>]

Thanks Leo,
Please find my comments inline.

Sean Evoy
Rational Software - IBM Software Group
Ottawa, Ontario, Canada

"Treggiari, Leo" <leo.treggiari@xxxxxxxxx>
Sent by: cdt-dev-admin@xxxxxxxxxxx

04/16/2004 10:01 AM

Please respond to
cdt-dev

To	<cdt-dev@xxxxxxxxxxx>
cc
Subject	RE: [cdt-dev] Managed Build System Versioning Strategy

Hi Sean,
 
I’ve embedded some questions
& comments regarding your proposal.
 
Regards,
Leo
 
-----Original Message-----
From: cdt-dev-admin@xxxxxxxxxxx [mailto:cdt-dev-admin@xxxxxxxxxxx]
On Behalf Of Sean Evoy
Sent: Thursday, April 15, 2004 3:58 PM
To: cdt-dev@xxxxxxxxxxx
Subject: [cdt-dev] Managed Build System Versioning Strategy
 

OK, 
Here, as promised, is my suggestion for versioning the managed build system.

The ManagedBuildManager is the heart of the build system in terms of reading
in the manifest where the tool definitions are located (plugin.xml) and
loading build information for existing projects (.cdtbuild). It needs to
know whether or not it can read the a given manifest or project file and
make sense of what it finds. This will be very important going forward,
since we know that the schema for defining tools is not sufficient for
everyone's needs. As the schema changes, so too will the manifest and,
by extension, the project files.

I propose creating a hard-coded PluginVersionIdentifier in the ManagedBuildManager.
A version identifier is comprised of a major, minor, and service component
(all integers), and a string qualifier. For example, reading the version
from an integration build would get an identifier like 2.0.0."200404140811".
For simplicity, the hard-coded version identifier in the build manager
will not have a qualifier, just the major, minor, and service components.
The version element is the only thing that has to be manually kept up-to-date
by the development team. I realize that hard-coding is a big, red flag
for most people, but in order to test, the info has to be stored somewhere.
I am open to alternative locations for the version info, of course.

When the ManagedBuildManager is asked to load the tool definitions, it
will ask the plugin what version it is (this is encoded in the plugin manifest
and easily available through the plugin descriptor). If the hard-coded
version is compatible with the version coming back from the plugin it will
load it. If not, it will throw a build exception. Really, it is a stretch
to even imagine that this will ever happen, but you never know ....

[Leo]  The plugin version
is the value of the plugin element, version attribute in the plugin.xml
file?  If so, are we going to dictate what this value needs to be
when defining a managed build plugin?  We currently use that attribute
for our product version.  Would it be better to define a new attribute
of the target element, e.g. managedBuildVersion?
 
[Sean] My initial thinking
was that I only wanted to maintain one hard-coded version string, and I
could get the plugin version from the plugin descriptor "for free"
in the sense that I did not have to add anything to the managed build schema.
As you say though, ISVs might be using the version information in the plugin
for their own internal purposes and forcing them to align with the CDT
numbering may be problematic. I can add a new element to the schema instead
of relying on the version. I want to think about whether this could help
address the issue that Chris raised about ISV-specific versions before
I leap.

What do you mean by “it is
a stretch to even imagine that this will ever happen”?   Do you mean
that you intend to support old target/tool definition schemas forever?
 That’s OK, I’m just not sure what you meant. 

[Sean] I mean that I don't
think the odds of someone taking a higher version of the plugins and force-feeding
them into an older version of the CDT are very high, and that's essentially
all this test can prevent. If an older version of the build manager gets
a newer version of a toolchain, it will only ask for the schema elements
it knows about, so the worst that can happen is the build info is incomplete.
I rather hope we do not have to support toolchain definitions for ever,
but so far, all of the changes to the schema have been additive, so reading
older plugin files has not been a problem.

Project build settings are also persisted in a file. The build manager
will write out a ProcessingInstruction containing the string equivalent
of its hard-coded version. When a project file is read in some time in
the future, the string will be compared to the hard-coded version, and
 one of three things will happen. If the file version is greater than
the hard-coded version in the build manager reading the file, it will throw
a build exception.
 
[Leo]  What code will
display a dialog box with an error message that the user can understand?
 
[Sean] Don't know yet, but
the front-runner is the properties page "constructor". Opening
the page forces a load from the project file intiially and that would be
a goodplace to catch the exception. Another possibility is to have the
build manager do a sanity on startup for all the projects in the workspace.
The thing is, this is an infrequent activity, so I don't want to spend
a lot of time covering off every possible work-flow that might result in
an older project file being opened. For example, if we ever do support
a build without the UI running, it would be possible for the makefile generator
to ask for build info for an older project. Assuming that a conversion
was needed, since there is no UI, no conversion would happen. However,
how reasonable is the user expectation that the project get upgraded automatically
in this case. If you upgradeyour software, usually you load your projects
into the UI before you build them just to be sure.

 If the file version is compatible,
it will read the file. If the file version is lower, it will call a project
file conversion routine to update the file (this might be a NOP if there
is no substantive changes between the two versions) and then read it.

Issues in no particular order:

·
        The absence
of a ProcessingInstruction indicates that a file is from CDT 1.2.x and
needs to be upgraded. 
·
        The only
project files we have to worry about right now are 1.2.x files, so we can
defer the discussion of our post-2.0 project file upgrade strategy if we
agree that the underlying logic/implementation is sufficient.

·
        As we
move forward, we may have to impose a limit on how many version we will
upgrade (i.e. by the time 4.0 rolls around will we have to be able to load
1.2.x project files?) 
·
        Should
we update project files silently or ask the user. A refusal results in
not reading in the settings (but the project will still be in the workspace).
Acceptance means the cdtbuild file is updated.

[Leo]  I think we have
to ask.  The reason is that after the conversion, the .cdtbuild file
will no longer work with older versions of Eclipse.
       
[Sean] Agreed.

·
        Should
the project converter be defined as an executable extension in the manifest
(so people implementing a toolchain can supply their own for their customizations).

[Leo]  This raises a more
“global” issue and is related to the previous item.  Imagine Eclipse
4.0 comes out and .project files need to be converted, .cdtproject files
need to be converted, .cdtbuild files need to be converted, and vendor
specific files need to be converted.  Does the user get asked for
each one?  This is bad since the user needs to convert all of them
or none of them or they will end up with a project that is not usable with
3.0 or 4.0!  This requires some coordination, for example an extension
point that any plugin can extend that gets called when upgrading a project
from an earlier version of Eclipse.  I haven’t thought about this
in any detail, but the extension interface might have 2 methods:
1.        isConversionNecessary(oldVersion,
newVersion) – Eclipse would ask each plugin that provides an extension
whether it needs to perform a conversion.  If any plugin answers “yes”,
then Eclipse displays the UI asking if the user wants to convert.
2.        Convert(oldVersion,
newVersion) – If the user agrees to the conversion and the plugin answered
“yes”, Eclipse calls this method to allow the plugin to do the conversion.

[Sean] I think we are on the
same page here.

Please let me know if there is anything critical that I have overlooked
and feel free to supply any feedback you have. Of course, time is of the
essence .... 

Thanks, 

Sean Evoy
Rational Software - IBM Software Group
Ottawa, Ontario, Canada