Set up an explicit backward compatibility policy

[tvercaut]

A discussed in #197, we agreed on following semver for version numbering. This implicetly means we agree on maintaining backward compatibility until major version changes.

It might be good to make the backward compatibility policy more explicit. By means of example, TensorFlow documents their backwards compatibility policy quite well: https://www.tensorflow.org/guide/versions

For MONAI, enforcing bacward compatibility acording to semver might also mean introducing an "experimental" folder or similar within MONAI where features that are ready for real-world testing but not yet for backward compatibility can be placed.

[tvercaut]

A bit of a side question in this issue but note that semver and PEP440 are incompatible when it comes to pre-release numbering (see also semver/semver#483). Given the pythonic ambition of MONAI, having PEP440 prevail over semver for this particular point would probably make sense.

[IsaacYangSLA]

Proposed statement on backward compatibility policy:

MONAI versioning policy follows PEP440 as follows

X.YaN   # Alpha release
X.YbN   # Beta release
X.YrcN  # Release Candidate
X.Y     # Final release

The common understanding on backward compatibility applies.

• Backward compatibility across MAJOR (X in the example above) is not guaranteed.
• Backward compatibility in private API across MINOR (Y in the example above) is not guaranteed.

For releases with MAJOR == 0, public API can change at any time.

[tvercaut]

Having a third component would make it closer aligned with semver and should remain compatible with PEP440. I would suggest following the modified semver called "Linux/Python Compatible Semantic Versioning 3.0.0" from openstack:
https://docs.openstack.org/pbr/3.1.1/semver.html

Releases would be tagged with

X.Y.Z.aN             # Alpha release
X.Y.Z.aN.devM   # Dev version for an alpha release
X.Y.Z.bN             # Beta release
X.Y.Z.rcN            # Release Candidate
X.Y.Z                   # Final release
X.Y.Z.devM         # Dev version for a final release

[tvercaut]

Related discussion in #2158

[rijobro]

Also related PR: #2171.

[ericspod]

Another PR: #2338

[wyli]

Here are some discussion points for the potential feature classifications:

Stable
Feature with code, documentation, tutorial ready, available in the milestone releases

• Relatively long-term maintenance (Pin down a few versions of pytorch/cuda for full tests)
• Breaking changes with notice/warnings one milestone release ahead of time
• Maintain an API changelog, migration guides
• Available using “pip install” and “docker image”
• Have pre-compiled binaries if it’s in c++/cuda? (via the release page)

Beta
Feature with code and some documentation, available in the milestone releases

• May not have thorough tests for extensive use cases
• May change in the next release without backward compatibility warnings
• Available using “pip install” and “docker image”
• May have pre-compiled binaries if it’s in c++/cuda? (via the release page)
• May have a separate warning decorator indicating the API is subject to change?

Experimental
on one of the branches other than “dev”, “main”

• With status: Discussion/InProgress/Rejected
• Made available via github (not pypi or milestone docker image)
• Include proposals for significant design changes
• Requires timely review from the core team
• Frequently check the compatibility with the dev and/or main

[wyli]

For making public API breaking changes, using the deprecation utils in monai:

1. discuss the breaking changes during pull requests or in dev meetings with a feature proposal if needed.
2. add a warning message in the upcoming release (version x.y), the warning message should include a forecast of removing the deprecated API in:
   • major x+1 minor 0 the next major version if it's a significant change,
   • major x minor y+2 the minor version after the next one, if it's a minor API change (this is not consistent with the semantic versioning).
3. add new test cases by extending the existing unit tests to cover the modified API.
4. collect any feedback from the users during the subsequent few releases, reconsider step 1 if needed.
5. before each release, review the deprecating APIs, clean up removed APIs described in step 2.

cc @Nic-Ma @ericspod @rijobro let's also discuss these at the next dev meeting.

[rijobro]

The forecast of removal version is currently an optional argument. Should we make it required so that we always know when we expect something to be removed? I also think that the docstring:

removed: version at which the argument was removed and no longer usable.

should be more like:

remove: version at which the argument will be removed and no longer usable.