[pde-ui-dev] Re: PDE API tooling

[Darin Wright <Darin_Wright@xxxxxxxxxx>]

I'm posting some more good questions...

> 
> I have some questions about the use cases for the API tools.
> 
> One of the things that's very important for our development teams
is
> that they correctly follow the Eclipse version number rules for 
> their plug-ins as they submit changes to the daily builds.  We
> currently have a tool that we run as part of our builds to check 
> this.  It takes as input the current built plug-in, the last
shipped
> built version of the same plug-in, and produces a status and a 
> report.  The status is good if the version numbering rules were
> correctly followed and bad otherwise.  The report contains more
> detail about the violations in the case of bad status.  Are you
> planning to produce a similar tool?  Note that, for use in the
> build, we require batch mode operation.  Of course, any tool
that 
> the build uses should also be available to developers in the IDE.

Yes, we are planning to provide support in the IDE
to detect invalid plug-in version numbers. This feature is based on the
deltas produced when comparing plug-ins. The delta engine is designed to
run without OSGi and could be invoked by a build/releng process. We also
plan to incorporate this into the Eclipse build process to produce simple
reports. We also intend to leverage the support to report invalid package
export version numbers. The related bug reports are:

        https://bugs.eclipse.org/bugs/show_bug.cgi?id=213019
        https://bugs.eclipse.org/bugs/show_bug.cgi?id=215073

> 
> Along these lines, there's an obscure but important special case of
> version number violations that we need to implement for our builds.
> There are times when the built content of a plug-in changes even 
> though its source hasn't changed.  We need to be able to detect
this
> and, at the very least, report that it happened.  One way for
this 
> to happen is if plug-in A contains the definitiion of a final 
> variable and plug-in B uses that variable.  Plug-in A changes
the 
> value of the variable, and plug-in B gets rebuilt with the new 
> version of plug-in A.  This newly built version of plug-in B
is 
> different from its previous version.  However, since we base
the 
> version numbers of plug-ins on the versions of the source files, the
> version number of B didn't change.  I have two questions about
this 
> situation --
> Are you planning to detect this case in any of
your tooling?

This is an interesting case. We do detect when a constant
field changes value and report this as a binary incompatibility problem.
That is, if you change the value of a constant, this breaks clients that
reference the constant. (I can't recall if this is only for static finals,
or finals in general - Olivier will be able to tell us).

So, I would consider such a change a "breaking
API" change. In this case plug-in A must increment its major version
segment (described here: http://wiki.eclipse.org/index.php/Version_Numbering).
Plug-in B in it's original form should still require a lower version range
of plug-in A. In order to work with the new version of A, B needs to be
re-built and update its required version range for A. I would expect that
B also needs to note this change by incrementing its maintenance segment
(although, John Arthorne is the expert on version numbering and might be
able to shed more light on this). B has not changed any API, but the new
version of B only works with the new version of A, and does not work with
the previous version of A.

> If we were to write a tool to detect this, is
there any code in the 
> current API tooling that we could leverage to solve this problem?
 
> The only solution that we've so far conceived is to do a binary 
> compare of the two versions of the built plug-in, filtering out the
> volatile information in the process of doing the compare.
> 

The summary is that we detect this problem as a binary
incomatibility. We would also detect/report that plug-in version numbers
need to be incremented. Our tooling does not currently detect the lower
bound of A that B is compatible with. We would like to enhance the tooling
to do this in the future.

Darin Wright