10 Covenants

Ten Covenants of API Evolution: https://emptysqua.re/blog/api-evolution-the-right-way/

First Covenant: Avoid Bad Features

Your goal is not to provide features that can be used to bite users, it's to provide features that work and don't have weird subtle behaviors

"It would have been better if this bad feature were never implemented at all."

Second Covenant: Minimize Features

To avoid bad features, add few features in general!

Features are like children: conceived in a moment of passion, they must be supported for years.

Third Covenant: Keep Features Narrow

You don't want a feature that, if abused, breaks everything ever and changes the very foundational nature of what your library does.

Fourth Covenant: Mark Experimental Features "Provisional"

Don't get locked into a dumb feature - if you aren't sure you really want to keep it, mark it as experimental/provisional. Next release, keep what works (mark it official) and discard what doesn't.

Fifth Covenant: Delete Features Gently

This is a promise responsible creators make

Follow a set of steps - add the new method, deprecate the old method (use Python warnings module), There’s a few steps involved in deleting a feature gently. Starting with a lizard that walks with its legs, you first add the new method, “slither”. Next, deprecate the old method.

Modify unittests so that warnings (which will not normally cause tests to fail) will become exceptions (which will cause the tests to fail):

> python3 -Werror::DeprecationWarning script.py

Sixth Covenant: Maintain a Changelog

keep a changelog

announce when a feature is added or deprecated or deleted