Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[] Conventions for out-of-cycle fixes

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

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.

Back to the top