[eclipse.org-architecture-council] Conventions for out-of-cycle fixes

[David M Williams <david_williams@xxxxxxxxxx>]

As mentioned on last Architecture Council
call, I plan to post a new page on the Eclipse Wiki, and a link to it from

http://wiki.eclipse.org/index.php/Development_Conventions_and_Guidelines

The content below is my first draft,
please feel free to make suggestions or improvements ... or state your
outright objection if you think its a bad idea. 
And, of course, even after published
on the wiki, it can be improved over time if others have better ideas,
or clarifying remarks. 

If I hear no out-right objections, I'll
post to wiki around 2/27. Of course, replies of agreement would be appreciated
too. 

In particular, I've never used the "create
feature patch" provided by PDE feature in Eclipse, so don't really
know if its relevant to this 
topic, or provides any help ... if anyone
else knows, I'd appreciate the education. 

Thanks all, 


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

Conventions and best practices for out-of-cycle
fixes

Sometimes adopters of Eclipse are tempted
to proved patches to official Eclipse provided jars, usually in order to

satisfy some critical situation with
their (sometimes paying) customers. This can be problematic, since if not
done properly, this might cause adjunct bugs. For example, 
it might interfere with or negate future
updates due to conflicts in version numbers. Also, it can be problematic
if the version number is not changed at all, then other side-effect bugs

are near impossible to track down, and
can waste many peoples time tracking down a bug in something that is not
what it appears to be. 

While there's no perfect solution to
this situation, there are some guidelines and best practices which can
reduce the probability of adjunct problems. So, hopefully these following

guidelines will prove useful to those
considering distributing a "private patch" to their customers.


1. Do not do provide an unofficial,
out-of-cycle fix. 

This first rule may sound contradictory
with the topic of this page, but it is a reminder to provide an unofficial
"private patch" only as a last resort. Be sure to make it clear
to the project that owns the buggy code that you are considering this,
and many Eclipse projects would willing to provide an emergency fix for
a critical situation for a truly blocking bug --- or, at least provide
a maintenance release in a timely fashion. But, this isn't guaranteed,
and there's often honest judgement differences in what constitutes a blocking
bug. So, if this first options doesn't help, read on. 

2. Do not provide a "private patch"

This means that if you are providing
an unofficial, out-of-cycle patched plugin, there's usually no reason to
do it "in secret". While no confidential data should ever be
revealed, often bug reports, with a clear statement of how a bug was fixed,
what version number was used for the patched plugin would not be out-of-order.
Again, there's no guarantee a project can (or will) "honor" this
information, but most good Eclipse citizens will make an effort to. 

3.  Gain project agreement on the
fix

In your bug report for the blocking
bug, provide your proposed patch, and see if the project committers would
agree that your fix is either correct, and would be in future maintenance
releases, or is at least compatible with what a future fix might be. Again,
there can be no guarantees, but if a project committers agrees in principle,
this at least reduces the probability of future adjunct bugs. 

While I am no lawyer and do not intend
to give legal advice, but I have heard some say the conditions of the Eclipse
License Agreement is such that if the source code is modified, then that
modified code must also be open source, and providing it in an Eclipse
bugzilla report is one way to make it "open". 

4. (re)Version the patched plugin and
feature

Both the fixed plugin, and the feature
that normally contains it, should be give a version number that matches
the original in major, minor, and service fields, but which increments
the qualifier field. 
The increment in the qualifier field
should be such that it "fits in" to the projects scheme of providing
version qualifiers, but which also uniquely identifies the patched plugin
as a patch. For example, 
if original version was 1.0.1,v20060101
an appropriate patched plugin might be 1.0.1.v20060501-patchA  ...
or similar, where date stamp is the current date when the patch was provided.


5. Produce consistent byte codes

The plugin with the fix should be compiled
in a way consistent (or identical) to the way the project produced the
byte codes to begin with, using the same compiler, the same java libraries,
the same compiler options. This is to minimize an tiny differences in the
fixed code, so that the only difference is the intended fix. (In theory,
this should be no great concern, but occasionally, if different compiler
is used, it can expose JIT bugs, etc., that are notoriously hard to track
down. 

So, to conclude, there are not guarantees,
but hopefully these guidelines help spell out the expectations, and some
measures to minimize adjunct problems.