What is the right way (and what is the right time) to break backwards compatibility?

(Gabriel A. Devenyi) #1

Just as the title says. Should you print a depreciation warning, for how long?

What about when the code changes don’t break the old methods, just make the results they’re getting wrong? Do you explicitly break compilation so that they can’t get the wrong answer?

(Dženan Zukić) #2

The right time is now, before ITK 5.0 release.

And explicitly breaking compilation is a popular way of handling the change :smile:

(Matt McCormick) #3

Backwards compatibility could relate to API or behavior or features.

Since we generally follow semantic versioning, backwards incompatible changes should be made in major releases, when the major version is changed, i.e. ITK 4 to ITK 5 as noted by @dzenanz. This helps users have an expectation that they can upgrade feature releases without many issues but expect that a few changes may be needed for updates to the major version.

Backwards incompatible changes should be accompanied by a note in the migration guide.

A deprecation warning should be added and kept around nominally until the next major release. However, this depends on how widely adopted the behavior was and its impact - it could be longer or shorter or not at all.

(Gabriel A. Devenyi) #4

Thanks @dzenanz and @matt.mccormick, that was my understanding of the goals of semantic versioning.

Is there a recommended way to add a warning if one wanted to do so?

(Matt McCormick) #5

@gdevenyi good question – there are some helpful LEGACY macros in itkMacro.h.