|
1 | | -Test Contribution Guidelines |
2 | | ----------------------------- |
| 1 | +Contribution Guidelines |
| 2 | +----------------------- |
3 | 3 |
|
4 | | -This is a guide on how to contribute test cases to help with coverage testing for NodeGit. |
| 4 | +### A Note on Issues and Support ## |
5 | 5 |
|
6 | | -## Getting Started ## |
| 6 | +We try to be available pretty often to help when problems come up. We like to split incoming questions |
| 7 | +into two categories: potential bugs/features, and questions. If you want a feature added, or think you've found a bug |
| 8 | +in the code (or in the examples), search the [issue tracker](https://github.com/nodegit/nodegit/issues) and if you dont |
| 9 | +find anything, file a new issue. If you just have questions, instead of using issues, contact us in our [Gitter room](https://gitter.im/nodegit/nodegit). |
7 | 10 |
|
8 | | -Currently there are a number of fields and functions in NodeGit that have no tests at all. A list of which files are missing and what fields and functions need tests can be generated by running |
| 11 | +## How to Help ## |
9 | 12 |
|
10 | | -``` bash |
11 | | -npm run generateMissingTests |
12 | | -``` |
| 13 | +NodeGit is iterating pretty quickly, but it can always go faster. We welcome help with the deeper darker parts, |
| 14 | +like the templates and binding and more, but there are plenty of smaller things to do as well. |
| 15 | +Things that are always needed: |
| 16 | + - Filing issues (see above). |
| 17 | + - Writing tests (See [here](https://github.com/nodegit/nodegit/blob/master/TESTING.md)). |
| 18 | + - Writing examples. |
13 | 19 |
|
14 | | -This will make the file `generate/output/missing-tests.json` which will contain info for tests or files that are currently missing. |
| 20 | +These are all good easy ways to start getting involved with the project. You can also look through the issue tracker |
| 21 | +and see if you can help with any existing issues. Please comment with your intention and any questions before getting |
| 22 | +started; duplicating work or doing something that would be rejected always sucks. |
15 | 23 |
|
16 | | -From this file you can find fields and functions that don't have any tests yet and pick one to work on. |
| 24 | +Additionally, [the documentation](http://www.nodegit.org) needs some love. Get in touch with one of us on Gitter if |
| 25 | +you'd like to lend a hand with that. |
17 | 26 |
|
18 | | -## Adding a test ## |
19 | | - |
20 | | -After you find a test that's missing the next step is to find or add the file that you need to add it into. You can always use other tests in the directory as a guide for writing more. All new files will be automatically added during a test run. |
21 | | - |
22 | | -In the `missing-tests.json` file you'll see it formatted like so: |
23 | | - |
24 | | -```json |
25 | | -{ |
26 | | - "{className}":{ |
27 | | - "fields": [], |
28 | | - "functions": [] |
29 | | - } |
30 | | -} |
31 | | -``` |
32 | | - |
33 | | -In the file each `{className}` corresponds to a file found at `test/tests/{classname}`. Each entry in either `fields` or `functions` is a missing test for the respective field/function. |
34 | | - |
35 | | -In the file that your test is going in you can just append it to the file inside of the `describe` function block. |
36 | | - |
37 | | -It can be helpful to reference the [libgit2 API docs](https://libgit2.github.com/libgit2/#v0.21.2) to know what the field or function is doing inside of libgit2 and referencing the [NodeGit API docs](http://www.nodegit.org/) can also help. Looking at examples inside of `/example` can show you how we wrap the libgit2 library and how you can call into it from JavaScript. |
38 | | - |
39 | | -The idea is to test the basic functionality of the field/function and to confirm that it's returning or setting the value(s) correctly. Bugs inside of libgit2 will have to either have a work-around or be ignored. |
40 | | - |
41 | | -If a specific field or function is further wrapped via a file inside of `/lib` then as long as that wrapper is called and tested. |
42 | | - |
43 | | -You can mark something to be ignored inside of the `/generate/missing-tests-ignore.json` file. |
44 | | - |
45 | | -After you write your test make sure to run `npm run generateMissingTests` again to confirm that the field/function that a test was written for no longer shows up. |
46 | | - |
47 | | -## Test results ## |
48 | | - |
49 | | -### The test passes ### |
50 | | - |
51 | | -Excellent!! Make sure that the test is working correctly and testing what you're expecting it to test and then move onto the [next section](https://github.com/nodegit/nodegit/tree/master/test#making-a-pull-request). |
52 | | - |
53 | | -### The test fails ### |
54 | | - |
55 | | -This is also great! You just found something that wasn't properly covered in our generate scripts for wrapping libgit2. We'll have to further analyze what's going on and figure out how to fix it. |
56 | | - |
57 | | -For bonus points you could also include a fix in your pull request but that step is optional. |
58 | | - |
59 | | -## Making a pull request ## |
60 | | - |
61 | | -So you made your self a new test for NodeGit and now you want to add it to the main repo? That's great! We'll try and make the process as simple and easy as possible for you. |
62 | | - |
63 | | -So assuming that you have a fork of the repo make a new branch that's labeled `new-tests-{className}` where {className} is the name of the file you added the tests to. Also, make sure you check the [main repo's pull request list](https://github.com/nodegit/nodegit/pulls) and see if somebody else is editing that file before you make your PR. They might have added a test already that's waiting to get merged in. |
64 | | - |
65 | | -So after you have your branch and your change is ready to go make sure your subjects for your commits contain the {className} of the tests you added and then list each new field/function being tested inside of the subject of the commit message. |
66 | | - |
67 | | -Example: |
68 | | - |
69 | | -``` |
70 | | -Added tests for oid |
71 | | -
|
72 | | -fromString |
73 | | -allocfmt |
74 | | -inspect |
75 | | -``` |
76 | | - |
77 | | -This will help us know what each commit contains at a glance and should expedite merging your pull request. |
78 | | - |
79 | | -If your test is failing, TravisCI should pick it up and note it on the PR. PR's that add failing tests will have to be handled on a case-by-case basis but please don't let that stop you from staring a PR. |
80 | | - |
81 | | -Please don't start a PR until you're finished (no WIP test PRs please!). |
| 27 | +For anything else, Gitter is probably the best way to get in touch as well. Happy coding, merge you soon! |
0 commit comments