API Changes and Stability
CCL follows the conventions of semantic versioning. Semantic versioning is a consistent set of rules for constructing CCL version numbers so that CCL users can understand when new releases have backwards compatible APIs.
An API breakage is anything that modifies the name or call signature of an
existing public-facing function or variable in the Python
code in such a way
that the change is not backwards compatible. For example, removing a Python
keyword
argument is an API breakage. However, adding one is not. Significant changes to the
behavior of a function also count as an API breakage (e.g. if an assumption is
changed that causes different results to be produced by default). Fixing a bug
that affects the output of a function does not count as an API breakage, unless
the fix modifies function names and arguments too as described above.
If the API is broken, the CCL major version number must be incremented (e.g. from
v1.5.0 to v2.0.0), and a new tagged release should be made shortly after the
changes are pushed to master. The new release must include notes in
CHANGELOG.md
that describe how the API has been changed. The aim is to make
it clear to users how their CCL-based code might be affected if they update to
the latest version, especially if the update is likely to break something. All
API changes should be discussed with the CCL team before being pushed to the
master
branch.