Long term API compatibility for fast-moving projects

Welcome to Compat Patcher Core, a mini-framework to build Compatibility Patchers. These companion applications allow your favorite software (a framework, a library...) to keep long term API stability towards its ecosystem (plugins, bridges to other applications...), while still keeping the main codebase clean, and getting new features at a good pace.

Compatibility Patchers inject backward/forward compatibility shims (like class/function/attribute aliases), restore features which were dropped/externalized because "not used enough" or "outside the scope of the library", and tweak the signatures and behaviour of callables (eg. for arguments which disappeared, or which became mandatory). It can even setup lazy "import aliases", so that code can import a moved module both from its old and new location.

These shims allows you to upgrade your dependencies one at a time, when their maintainer finally had some time for a code update, or when missing features and bugfixes justify a fork. Most importantly, they allow you to not get stuck, when deadlines are tight, and crucial dependencies have conflicting expectations regarding the software version.

Note that compatibility Patchers are not supposed to undo changes related to security (default access permissions, markup escaping, cookie parameters...), because of the risks involved. Also, changes that only impact project-level code (eg. new mandatory settings) should not get patched, since it's easier and cleaner for to simply update project code.

Technically, Compatibility Patchers are packages which manage a set of fixers, tiny utilities (often less than 10 lines of code) which advertise the change that they make, the software versions that they support, and which patch the target code on demand. By applying these fixers in a proper order (sometimes before, sometimes after the initialization of the patched software itself), Compatibility Patchers can easily "time travel", and work around multiple breaking changes which target the same part of the code (e.g. a content handler being added and then removed).

Compat Patcher Core holds the core logic of that system, via easily extendable classes: a registry system, monkey-patching utilities, and a generic runner to be called at the very start of your application. It also contains a cookiecutter recipe to setup your own Compatibility Patcher in a few minutes, with test scaffolding and packaging metadata ready for launch.

Documentation is available on Read The Docs

Sources are available on Github

Which applications currently benefit from this system?

• The Django Web Framework via Django-Compat-Patcher