Compatibility management

[martinbudden]

This post is not an issue in itself, rather it's a post to define and discuss the vocabulary and practices of compatibility management, so when compatibility is discussed in other issues and pull requests there is a common vocabulary used, and an understanding of how compatibility is [usually/often] managed in software projects.

I don't normally like to blow my own trumpet, but in a "past life" I was Chief Software Architect of the Symbian operating system (an OS that, before the advent of Android and the Apple phone, was used in hundreds of millions of smartphones). Part of my responsibility was managing compatibility across OS releases, so this is an area in which I have considerable expertise. This was an important issue for the OS and we had a team of people (reporting to me) who managed this in conjunction with the owners of the OS components.

So, some definitions:

1. compatibility break is some thing that, when introduced, stops a dependent system, subsystem, tool, or any other dependency from working. For simplicity I'll just use the term system. "Not working" can mean a number of things, including:
   1. the system won't even build
   2. the system returns different results
   3. the system runs too slowly
   4. the system consumes too many resources, and so, in a resource limited environment can no longer run
2. A forced compatibility break (or forced break), is a break that requires the users to make changes when they move to the new release
3. A managed compatibility break (or managed break) is a break that allows the users to upgrade to the new release without making any changes at the time of making the upgrade, and migrate their code to accept the break on their own timescale.

Generally speaking compatibility breaks should be avoided, but if unavoidable they should be managed and their impact on the users should be minimised.

It is important that compatibility breaks are managed because users often want to upgrade to a new release to take advantages of the features of that release, but not want to incur an immediate cost of changing their codebase to accept the upgrade.

If you follow the writings of anyone responsible for a software system (eg Bjarne Stroustrup for C++, Guido van Rossum for Python, or Linus Torvalds for Linux) you know that managing compatibility is a large and important part of that responsibility.

Managing breaks

There are a number of established ways to manage compatibility breaks, these include:

1. Introducing the new functionality while deprecating the old. For example a new function or class or keyword could be introduced and the old one deprecated
2. An in-source directive to switch on the new functionality. For example the use of a pragma in C or import from __future__ in Python.
3. A build flag that the user can switch on when they are ready to accept the break

[t-paul]

Moved to https://github.com/openscad/openscad/wiki/Compatibility-management

[martinbudden]

Great, thanks. I'll close the issue.