Skip to content

Latest commit

 

History

History
102 lines (74 loc) · 3.75 KB

CONTRIBUTING.md

File metadata and controls

102 lines (74 loc) · 3.75 KB

General

While this project is in the OCaml Labs organization, contributions from others are very much welcome. We're trying to build a tool that works for many users.

If you're unclear whether a feature would fit the scope of dune-release don't hesitate to open an issue to gauge the interest.

Setting up your working environment

If you want to contribute to the project you'll first need to install the dependencies. You can do it via opam:

$ git clone [email protected]:ocamllabs/dune-release.git
$ cd dune-release
$ opam switch create ./ ocaml-base-compiler.4.13.1 --deps-only -t

This will create a local switch with a fresh compiler, the dependencies of dune-release and the dependencies for running the tests. The exact OCaml version is just an example, you should be able to use any reasonably recent version of OCaml.

From there you can build dune-release by simply running:

$ dune build

and run the test suite with:

$ dune runtest

Tests

In a effort to cover as much of the codebase with tests as possible, new contributions should come with tests when possible/it makes sense.

dune-release uses dune's cram tests extensively to make sure the workflows work as expected and don't break for our users.

Unit testing

We should aim at improving the unit tests coverage as much as possible. Our unit tests can be found in tests/lib/. They are written using the alcotest testing framework. If you want to add new tests, we encourage you to reuse the style used in the existing tests (test_vcs.ml is a good example).

There should be one test module per actual module there. The test runner is tests.ml. If you add tests for a new or so far untested module, don't forget to add its test suite to the runner.

For each function we test, we build a list of Alcotest unit test_case. It's important to try to be consistent in that regard as it makes the output of the test runner more readable and helps with fixing or investigating broken tests.

For each module, we then have one Alcotest unit test that contains the concatenation of all the test cases.

That results in the following test output for a successful run:

$ dune runtest
       tests alias tests/lib/runtest
Testing `dune-release'.
This run has ID `14602E98-BFF4-4D74-A50A-56466A3F2C5B'.

  [OK]          Github                 0   Parse.ssh_uri_from_http https://gi...
  ...
  [OK]          Github_repo           15   from_gh_pages: https://user.github...

Full test results in `.../_build/default/tests/lib/_build/_tests/dune-release'.
Test Successful in 0.017s. 95 tests run.

End-to-end testing

End-to-end tests directly call the dune-release binary and make sure it behaves in the expected way. They live in the tests/bin/ directory.

We have one folder there per aspect we want to test, for instance the tests for determining the version from a tag live in version-from-tag/.

Make sure to only output relevant information in your test by e.g. postprocessing the output with grep and the usual POSIX tools. This makes the test more relevant, easier to read and less fragile should other things change.

If these tools don't suffice/are not portable there is an OCaml helper binary tests/bin/helpers/make_dune_release_deterministic that can be extended to make the output more deterministic and can be used to filter output in the cram tests.

If your tests change behavior but the change is correct you can use dune promote to update your test file so the next run of dune runtest will expect the new behavior.