Simple warning goes a long way

TL;DR;

Just warn people with a simple message when you are deprecating a behavior in your tool and you are introducing a breaking change. It’s not that difficult

Story

Yesterday I kind of wake up to a nasty surprise in our local Continuous Integration.

Continuous Integration on Jenkins failing miserably

The problem

Prettier (https://github.com/prettier/prettier/) have released a breaking change from version 1.19.1 to 2.0.1. This breaks most of our projects.

The bigger problem

Prettier is one of the nicest tools we’ve used. It allows us to keep the code formatted. It is also integrated in our CI and if a file is not properly formatted when committed the build fails.

Several months ago it took us 17.5 hours to integrate Prettier to all developers and all projects and since then we had no problems.

Then the update happened.

I have nothing against breaking changes in an API or a project. I welcome them especially in non-critical tools as formatting the code. People learn. People need to learn and building and maintaining an API takes practice, consideration and a lot of experience. I have personally broken some API(s) that I’ve developed in the past. But what I think about breaking changes is that you should properly communicate this with you clients. We are using prettier in a very simple way. Here is the command:

npx prettier app/**/*.js test/dummy/spec/javascripts/**/*_spec.js vendor/assets/javascripts/gcc/externs/*.externs.js --write --config prettier_conf.json"

That’s it. Turns out that as of version 2.0.1 prettier have broken this behavior and now if the project has no files for any of the globs it will return an error.

For version 2.0.1

$ mkdir pretti
$ cd pretti/
/pretti$ touch some.js
/pretti$ npx prettier --version
2.0.1
/pretti$ ls
some.js
/pretti$ npx prettier app/**/*.js *.js
[error] No files matching the pattern were found: "app/**/*.js".
/pretti$ echo $?
127

For version 1.19.1

$ mkdir pretti
$ cd pretti/
/pretti$ touch some.js
/pretti$ npx prettier --version
1.19.1
/pretti$ ls
some.js
/pretti$ npx prettier app/**/*.js *.js
/pretti$ echo $?
0

See what they did there. Previously if a pattern was not matched prettier returned 0 and now it returns 127, which for a Linux is just error.

Conclusion and solution

“Professionals have standards”

When designing tools have Interoperability in mind. Do breaking changes, but release a version that warns people for the deprecation and for the breaking change they are about to experience. Like a simple print to console in version 1.99 (the one before the breaking change) that says “hey, this is deprecated and will be removed in 2.0. Please read here ‘link’ so that your clients don’t break, you don’t open issues on our github and you don’t write blog posts. Stay safe.”