Developers Guidelines

theindigamer edited this page Jul 18, 2017 · 14 revisions

Developers Guidelines

Include tests in your patches

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.

Code style

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.

Git Branches

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.

Tests

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/.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.