Backwards Compatibility

tl;dr: If your code works (with no deprecation warnings) on version i, your code should continue to work on version i+1.

Swift for TensorFlow is evolving quickly; it's important that we maintain development velocity as we iterate on building APIs for deep learning in Swift. Simultaneously, we're seeing increasing adoption of S4TF, and as a result, stability and maintainability is increasingly important. These two desires are in tension with each other.

To balance these opposing needs, we follow these rules (in-place since S4TF 0.5+):

• Backwards compatible changes (e.g. new additions) can be regularly introduced.
• Renaming symbols (e.g. types, functions) should be done over two consecutive releases. In the first release, the new name is introduced and the old name is marked deprecated (using Swift's availability e.g. @available(*, deprecated)). In the second release, the deprecated symbol can be removed.
• Removing symbols also occurs over a 2 release process where in the first release the symbol is marked as deprecated (see above), and is removed in the second release.

Rationale: these additional restrictions on top of SemVer allows users to decouple the version bump with the upgrade of their code.