From 1dbd017c43d7898fc10c2e9da155c3fd6dc1251c Mon Sep 17 00:00:00 2001 From: Simon Cruanes Date: Tue, 13 Jun 2017 18:20:29 +0200 Subject: [PATCH] more on contributing in readme --- README.adoc | 48 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/README.adoc b/README.adoc index ebd2256c..2e7d17bb 100644 --- a/README.adoc +++ b/README.adoc @@ -137,16 +137,54 @@ To build the small benchmarking suite (requires https://github.com/chris00/ocaml == Contributing -PRs on github are welcome (patches by email too, if you prefer so). +PRs on github are very welcome (patches by email too, if you prefer so). -A few guidelines: +[[first-time-contribute]] +=== First-Time Contributors + +Assuming your are in a clone of the repository: + +. Some dependencies are required, you'll need + `opam install benchmark qcheck qtest sequence`. +. run `make devel` to enable everything (including tests). +. make your changes, commit, push, and open a PR. +. use `make test` without moderation! It must pass before a PR + is merged. There are around 900 tests right now, and new + features should come with their own tests. + +If you feel like writing new tests, that is totally worth a PR +(and my gratefulness). + +=== General Guidelines + +A few guidelines to follow the philosophy of containers: - no dependencies between basic modules (even just for signatures); - add `@since` tags for new functions; -- add tests if possible (using `qtest`). +- add tests if possible (using https://github.com/vincent-hugot/iTeML/[qtest]). There are numerous inline tests already, +to see what it looks like search for comments starting with `(*$` +in source files. -It is helpful to run `make devel` to enable everything. Some dependencies -are required, you'll need `opam install benchmark qcheck qtest sequence`. +=== For Total Beginners + +Thanks for wanting to contribute! +To contribute a change, here are the steps (roughly): + +. click "fork" on https://github.com/c-cube/ocaml-containers on the top right of the page. This will create a copy of the repository on your own github account. +. click the big green "clone or download" button, with "SSH". Copy the URL (which should look like `git@github.com:/ocaml-containers.git`) into a terminal to enter the command: ++ +[source,sh] +---- +$ git clone git@github.com:/ocaml-containers.git +---- ++ +. then, `cd` into the newly created directory. +. make the changes you want. See <> for + more details about what to do in particular. +. use `git add` and `git commit` to commit these changes. +. `git push origin master` to push the new change(s) onto your + copy of the repository +. on github, open a "pull request" (PR). Et voilà ! Powered by image:http://oasis.forge.ocamlcore.org/oasis-badge.png[alt="OASIS", style="border: none;", link="http://oasis.forge.ocamlcore.org/"]