TripleO has run with good but not perfect backwards compatibility since creation. It’s time to formalise this in a documentable and testable fashion.
TripleO will follow Semantic Versioning (aka semver) for versioning all releases. We will strive to avoid breaking backwards compatibility at all, and if we have to it will be because of extenuating circumstances such as security fixes with no other way to fix things.
TripleO has historically run with an unspoken backwards compatibility policy but we now have too many people making changes - we need to build a single clear policy or else our contributors will have to rework things when one reviewer asks for backwards compat when they thought it was not needed (or vice versa do the work to be backwards compatible when it isn’t needed.
Secondly, because we haven’t marked any of our projects as 1.0.0 there is no way for users or developers to tell when and where backwards compatibility is needed / appropriate.
Adopt the following high level heuristics for identifying backwards incompatible changes:
Corollaries to these principles:
Other sorts of changes may also be backwards incompatible, and if identified will be treated as such - that is, this list is not comprehensive.
We don’t consider the internal structure of Heat templates to be an API, nor any test code within the TripleO codebases (whether it may appear to be public or not).
TripleO’s incubator is not released and has no backwards compatibility guarantees - but a point in time incubator snapshot interacts with ongoing releases of other components - and they will be following semver, which means that a user wanting stability can get that as long as they don’t change the incubator.
TripleO will promote all its component projects to 1.0 within one OpenStack release cycle of them being created. Projects may not become dependencies of a project with a 1.0 or greater version until they are at 1.0 themselves. This restriction serves to prevent version locking (makes upgrades impossible) by the depending version, or breakage (breaks users) if the pre 1.0 project breaks compatibility. Adding new projects will involve creating test jobs that test the desired interactions before the dependency is added, so that the API can be validated before the new project has reached 1.0.
Adopt the following rule on when we are willing to [deliberately] break backwards compatibility:
We also need to:
Set a timeline for new codebases to become mature (one cycle). Existing codebases will have the clock start when this specification is approved.
Set rules for allowing anyone to depend on new codebases (codebase must be 1.0.0).
Document what backwards compatible means in the context of heat templates and elements.
Add an explicit test job for deploying Icehouse from trunk, because that will tell us about our ability to deploy currently supported OpenStack versions which we could previously deploy - that failing would indicate the proposed patch is backwards incompatible.
If needed either fix Icehouse, or take a consensus decision to exclude Icehouse support from this policy.
Commit to preserving backwards compatibility.
When we need alternate codepaths to support backwards compatibility we will mark them clearly to facilitate future cleanup:
# Backwards compatibility: <....> if .. # Trunk ... elif # Icehouse ... else # Havana ...
Keeping code around longer may have security considerations, but this is a well known interaction.
End users will love us.
None anticipated. Images will be a marginally larger due to carrying backwards compat code around.
Deployers will appreciate not having to rework things. Not that they have had to, but still.
Developers will have clear expectations set about backwards compatibility which will help them avoid being asked to rework things. They and reviewers will need to look out for backward incompatible changes and special case handling of them to deliver the compatibility we aspire to.
None. An argument could be made for doing a quick cleanup of stuff, but the reality is that it’s not such a burden we’ve had to clean it up yet.
To ensure we don’t accidentally break backwards compatibility we should look at the oslo cross-project matrix eventually - e.g. run os-refresh-config against older releases of os-apply-config to ensure we’re not breaking compatibility. Our general policy of building releases of things and using those goes a long way to giving us good confidence though - we can be fairly sure of no single-step regressions (but will still have to watch out for N-step regressions unless some mechanism is put in place).
The users manual and developer guides should reflect this.