-
Notifications
You must be signed in to change notification settings - Fork 106
Developers Guidelines
Writing tests is mandatory. If you add or modify a Batteries feature, your patch must come with tests on the affected functions. We will not accept patches that don't come with the relevant tests. If you are doing performance optimizations, the patch must come with benchmarks measuring the performance changes.
Adding new tests to existing, untested or not-completely-tested functions is encouraged. Writing failing test for other people's code is extra encouraged.
Your tests should especially cover edge cases (empty list, argument 0...) and error cases, checking that the error returned is as specified.
See below for a quick description of our in-code testing methods. Looking at existing tested code will give you reasonable examples -- that you are welcome to improve.
Use comments liberally.
Faster is usually preferred over simpler, although faster and wrong loses.
Use labeled parameters liberally. ~f for functions, ~init for folding initialization values (what other common labels?). For examples, have a look at the Labels submodules for BatList or BatArray.
When reasonable, give the main data structure in a consistent argument location (always first argument, always last argument) -- sticking to the always last argument convention makes working with the pipe operator |> easier.
master is where day-to-day development goes. Backwards incompatible changes should not be done here. Backwards incompatible commits need to be applied to the next major release. As such, they should be applied in the v2 (or v3, etc.) branch. This branch pulls from master from time to time.
release is where public releases go. Tag all releases with their version, like v1.2.2.
Feature branches come off master and return to master. Name these whatever you like.
Release branches come off master and return to both master and release when they're done. Name them release-xxx. Only bugfixes go into release branches.
If needed. hotfixes can be created, coming off the release branch and merging back into it.
If/when the time comes that we need to cut releases to an old series while a new series is in development (e.g. making old 1.x releases while master builds towards 2.0), then we'll have an additional series-1.x branch which will act as master for that series.
Batteries supports inline tests in code, which are automatically extracted and run by make test. Automatically opened inside the tests are: Batteries, the module the test is in (i.e. BatEnum), and OUnit.
This inline unit test system is called qtest, and has comprehensive documentation.
For more delicate tests, for example if you want to provide functors testing different implementations of a same interface, you can write full tests, using the OUnit unit testing library, in the testsuite/ source directory. See testsuite/test_map.ml for example.
For performance tests, you can write benchmarks in the benchsuite/ source directory. See benchsuite/deque.ml for example.
You can see the coverage of the tests by running make coverage, and browsing coverage/index.html.
In addition, the coverage of the master branch is available at http://batteries.forge.ocamlcore.org/coverage/.