Check-break

check-break helps you to discover compatibility breaks in your code, and to improve decisions-making to determine if a new major version is required. In few words, if you follow semver (or try to stick to it), you must use check-break ;-)

check-break itself follows semver and monitors its own changes. For now, it's under heavy development, use it at your own risks, compatibility breaks could happen at every moment.

What is a compatibility break ?

Basically, following the semver definition :

A change is incompatible if it removes a possibility for the consumer in the public API.

All starts with a clear definition of public API in your context. Once done, a compatibility break occurs on all public API functions each time :

a function is removed
an argument is removed
an argument is added (without a default value)
a default argument is removed
a default value is changed
a return type is removed
a return type is added
type of any input / output / exception / assertion is changed and is incompatible with the former one (1)

1. In other words, if you're comfortable with Liskov principle, you might have heard :

Be contravariant in your preconditions, be covariant with your postconditions.

Thus, a compatibility break happens when you're covariant in your preconditions or contravariant in your postconditions.

Since check-break can't guess your public API (yet), it shows you all changes on public functions. It's up to you to determine if :

this change really is a break,
this change is in the public API scope.

First launch

(Assuming there's a golang env on your system)

make install

That's it.

Usage

This tool is based upon git, and particularly on diff between two points. Thus, the syntax is as follows :

$ check-break -s starting_point -e ending_point [-p path_to_git_repository] [-c path_to_config_file]

Note: All unsupported files are also reported as such, in order not to give a feeling of false negative.

Langages supported

Obviously, I started with langages I use in a daily-basis :

Go
Java
Javascript
PHP
sh

Feel free to participate to add yours, correct bugs, improve design, etc. check-break is under GPL3.

Please remember that this tool may be incomplete, it doesn't replace the human judgment.

check-break's People

Contributors

Stargazers

Watchers

check-break's Issues

Optional Path

Set -p (working path) as optional so it automatically uses current dir (pwd).

CB by AST

Building an AST, language dependent, will allow to deeply understand nature of changes, depending on languages.

Doing that will make us more accurate, for excluding false positive and providing detailed explanation.

Define a default value for config file

Config file has to be provided each time a precision in the analysis is required ; it's too rigid. It would be useful if check-break could automatically searches in the working dir a file name, for example cb-config.json. Doing that, each soft could set its own config, ie. public API definition, exclusions patterns, etc.

Recommend Projects