Merge pull request libgit2#2653 from ethomson/contributing

carlosmn · carlosmn · commit 65f6c1c7eb7b · 2014-11-09T13:41:57.000+01:00
Add test information to contributing guidelines
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -15,7 +15,9 @@ from them into your own application.
 
 ## Discussion & Chat
 
-We hang out in the #libgit2 channel on irc.freenode.net.
+We hang out in the
+[`#libgit2`](http://webchat.freenode.net/?channels=#libgit2)) channel on
+irc.freenode.net.
 
 Also, feel free to open an
 [Issue](https://github.com/libgit2/libgit2/issues/new) to start a discussion
@@ -34,10 +36,10 @@ and when a critical bug fix needs to be backported, it will be done on a
 
 First, know which version of libgit2 your problem is in and include it in
 your bug report.  This can either be a tag (e.g.
-[v0.17.0](https://github.com/libgit2/libgit2/releases/tag/v0.17.0) ) or a
-commit SHA (e.g.
-[01be7863](https://github.com/libgit2/libgit2/commit/01be786319238fd6507a08316d1c265c1a89407f)
-).  Using [`git describe`](http://git-scm.com/docs/git-describe) is a
+[v0.17.0](https://github.com/libgit2/libgit2/releases/tag/v0.17.0)) or a
+commit SHA
+(e.g. [01be7863](https://github.com/libgit2/libgit2/commit/01be7863)).
+Using [`git describe`](http://git-scm.com/docs/git-describe) is a
 great way to tell us what version you're working with.
 
 If you're not running against the latest `master` branch version,
@@ -52,11 +54,13 @@ out a way to help you.
 
 ## Pull Requests
 
-Our work flow is a [typical GitHub flow](https://guides.github.com/introduction/flow/index.html),
-where contributors fork the [libgit2 repository](https://github.com/libgit2/libgit2),
+Our work flow is a [typical GitHub
+flow](https://guides.github.com/introduction/flow/index.html), where
+contributors fork the [libgit2 repository](https://github.com/libgit2/libgit2),
 make their changes on branch, and submit a
-[Pull Request](https://help.github.com/articles/using-pull-requests) (a.k.a. "PR").
-Pull requests should usually be targeted at the `master` branch.
+[Pull Request](https://help.github.com/articles/using-pull-requests)
+(a.k.a. "PR").  Pull requests should usually be targeted at the `master`
+branch.
 
 Life will be a lot easier for you (and us) if you follow this pattern
 (i.e. fork, named branch, submit PR).  If you use your fork's `master`
@@ -75,11 +79,32 @@ also let others know that you are currently working on something.
 
 Before wrapping up a PR, you should be sure to:
 
-* Write tests to cover any functional changes (ideally tests that would
-  have failed before the PR and now pass)
+* Write tests to cover any functional changes
 * Update documentation for any changed public APIs
 * Add to the [`CHANGELOG.md`](CHANGELOG.md) file describing any major changes
 
+## Unit Tests
+
+We believe that our unit tests allow us to keep the quality of libgit2
+high: any new changes must not cause unit test failures, and new changes
+should include unit tests that cover the bug fixes or new features.
+For bug fixes, we prefer unit tests that illustrate the failure before
+the change, but pass with your changes.
+
+In addition to new tests, please ensure that your changes do not cause
+any other test failures.  Running the entire test suite is helpful
+before you submit a pull request.  When you build libgit2, the test
+suite will also be built.  You can run all tests by simply running
+the resultant `libgit2_clar` binary.  If you want to run a specific
+unit test, you can name it with the `-s` option.  For example:
+
+    libgit2_clar -sstatus::worktree::long_filenames
+
+Or you can run an entire class of tests.  For example, to run all the
+worktree status tests:
+
+    libgit2_clar -sstatus::worktree
+
 ## Porting Code From Other Open-Source Projects
 
 `libgit2` is licensed under the terms of the GPL v2 with a linking
@@ -112,9 +137,10 @@ function and type naming, code formatting, and testing.
 
 We like to keep the source code consistent and easy to read.  Maintaining
 this takes some discipline, but it's been more than worth it.  Take a look
-at the
-[conventions file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md).
+at the [conventions
+file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md).
 
 ## Starter Projects
 
-See our [projects list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md).
+See our [projects
+list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md).
