diff --git a/README.md b/README.md index 668f4c68c6..fa3a9ba1ff 100644 --- a/README.md +++ b/README.md @@ -117,3 +117,24 @@ Run the benchmarks: ```bash $ cargo +nightly bench --features="unstable" ``` + +Code coverage +--- + +To generate code coverage statistics, run kcov via Docker: + +```bash +$ docker run -it --rm --security-opt seccomp=unconfined --volume "$PWD:/volume" elmtai/docker-rust-kcov +``` + +Why coverage? While most see coverage as a code quality metric, we see it primarily as a developer +productivity metric. When a developer makes a change to the codebase, presumably it's a *solution* to +some problem. Our unit-test suite is how we encode the set of *problems* the codebase solves. Running +the test suite should indicate that your change didn't *infringe* on anyone else's solutions. Adding a +test *protects* your solution from future changes. Say you don't understand why a line of code exists, +try deleting it and running the unit-tests. The nearest test failure should tell you what problem +was solved by that code. If no test fails, go ahead and submit a Pull Request that asks, "what +problem is solved by this code?" On the other hand, if a test does fail and you can think of a +better way to solve the same problem, a Pull Request with your solution would most certainly be +welcome! Likewise, if rewriting a test can better communicate what code it's protecting, please +send us that patch!