Cleaning up code breaks binary compatibility

Question

I'm working on a project which is being used by a number of people I don't know. We've done a fairly good job of bringing down the CheckStyle warnings and the thing is about a low as its going to get without breaking binary compatibility.

The majority of the remaining warnings are caused by constants (public static final) missing the final keyword. The naming of the constants makes it clear that the developer intended them to be read only, but they simply didn't have final defined on them.

Unless a developer was writing some pretty terrible code that made use of this oversight, their code won't break if we add them.

Currently the version number is 1.2.1. Would you apply the change and go to 2.0, or apply it and roll it out as 1.3. Seems like a pretty small change to require a full 2.0.

What should I do?

Answer 1

I'm sure you already know this, but I suspect it has to come down to "is this a safe/simple/no-worry" upgrade?

• Point releases are considered safe and routine. They should consist entirely of bug fixes in some projects. Other projects will include new features if they are unlikely to cause problems.
• New major version releases contain evolutionary changes that may require adaptation
• New major x.0 version releases are considered highly suspect by sophisticated users :-)

I think it also depends on how close you are to the next major version release. If it's soon, don't risk a problematic point release. You can always do a safe point release and an alpha major release, but this might be odd if the next major release was way out in the future...

Answer 2

Unless a developer was writing some pretty terrible code that made use of this oversight, their code won't break if we add them.

Like creating subclasses of the previously non-final classes that will no longer work?

I think it should be 2.0 and that you should be keeping support to the 1.x series

Additionally here's an interesting video about APIs: "How to design a good API and why it matters" by Joshua Bloch creator so core libraries in Java and now working on Google

Answer 3

I say break them. If you are a mutating static then you have to know you are doing wrong. However, you might want to separate it into a different release so that clients have a chance (whether they take it or not) to upgrade smoothly, rather than in a panic because they need some other unrelated fix.

Answer 4

In my opinion, changes like this which could break binary compatibility should be held off until a major version is released. That is, your question shouldn't be "What version number should I use" but rather "when should I do these changes".

If you are totally committed to binary compatibility, you should put off these changes until a release that contains significant improvements justifying the cost of upgrades. For example, the KDE project imposes a binary compatibility requirement on major releases. This means that any improvements over the lifetime of that release can't break applications compiled against older versions. So developers wishing to clean up the code must wait until the next major version.

Once you are ready to release a major release with all its spiffy new features, go ahead and make whatever binary compatibility changes you feel are necessary, and in that case if something breaks it's not as surprising.

If you wanted to be clever you could implement a pre-processor and compile the code twice, once with finals and once without. This could be used as a stepping stone to true finals but the maintenance cost would be high in the meantime.