1 | # CONTRIBUTING to eslint-plugin-jsdoc
|
2 |
|
3 | ## Testing changes locally
|
4 |
|
5 | You might try a TDD approach and add tests within the `test` directory,
|
6 | to try different configs, you may find it easier to try out changes in
|
7 | a separate local directory.
|
8 |
|
9 | You can run [`npm link`](https://docs.npmjs.com/cli/link) for this purpose,
|
10 | pointing from your project to this project. For example, while in your project
|
11 | root and with `eslint-plugin-jsdoc` as a sibling, run:
|
12 |
|
13 | ```shell
|
14 | npm link ../eslint-plugin-jsdoc
|
15 | ```
|
16 |
|
17 | ## Building the project
|
18 |
|
19 | After running `npm install` to get the latest dependencies and devDependencies,
|
20 | you can run the following command to update the `dist` files, with `dist/index.js`
|
21 | being the `main` entrance point from `package.json`:
|
22 |
|
23 | ```shell
|
24 | npm run build
|
25 | ```
|
26 |
|
27 | ## Coding standards
|
28 |
|
29 | The project follows ESLint rules from [`canonical`](https://www.npmjs.com/package/eslint-config-canonical)
|
30 | and testing follows its subconfig, `canonical/mocha`.
|
31 |
|
32 | ## Testing
|
33 |
|
34 | Tests are expected. Each rule file should be in CamelCase (despite the rule names themselves being hyphenated) and should be added within `test/assertions` and then imported/required by
|
35 | `test/rules/index.js`.
|
36 |
|
37 | Each rule file should be an ESM default export of an object which has `valid` and `invalid` array properties containing the tests. Tests of each type should be provided.
|
38 |
|
39 | `parserOptions` will be `ecmaVersion: 6` by default, but tests can override `parserOptions`
|
40 | with their own.
|
41 |
|
42 | See ESLint's [RuleTester](https://eslint.org/docs/developer-guide/nodejs-api#ruletester)
|
43 | for more on the allowable properties (e.g., `code`, `errors` (for invalid rules),
|
44 | `options`, `settings`, etc.).
|
45 |
|
46 | Note that besides `npm test`, there is `npm run test-cov` which shows more
|
47 | detailed information on coverage. Coverage should be maintained at 100%, and
|
48 | if there are a few guards in place for future use, the code block in question
|
49 | can be ignored by being preceded by `/* istanbul ignore next */` (including
|
50 | for warnings where the block is never passed over (i.e., the block is always
|
51 | entered)). If you want to test without coverage at all, you can use
|
52 | `npm run test-no-cov`. To only test rules rather than other files, you
|
53 | can use `npm run test-index`.
|
54 |
|
55 | To test specific rules, you can supply a comma-separated list with the `--rule`
|
56 | flag passed to `test-index`, e.g., for `check-examples` and `require-example`:
|
57 |
|
58 | `npm run --rule=check-examples,require-example test-index`.
|
59 |
|
60 | You can further limit this by providing `--invalid` and/or `--valid` flags
|
61 | with a comma-separated list of 0-based indexes that you wish to include (also
|
62 | accepts negative offsets from the end, e.g., `-1` for the last item). For
|
63 | example, to check the first and third invalid tests of `check-examples`
|
64 | alon with the second valid test, you can run:
|
65 |
|
66 | `npm run --rule=check-examples --invalid=0,2 --valid=1 test-index`.
|
67 |
|
68 | ## Requirements for PRs
|
69 |
|
70 | PRs should be mergeable, [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
|
71 | first against the latest `master`.
|
72 |
|
73 | The number of commits will ideally be limited in number, unless extra commits
|
74 | can better show a progression of features.
|
75 |
|
76 | Commit messages should be worded clearly and the reason for any PR made clear
|
77 | by linking to an issue or giving a full description of what it achieves.
|
78 |
|
79 | ## Merging
|
80 |
|
81 | We use [semantic-release](https://github.com/semantic-release/semantic-release)
|
82 | for preparing releases, so the commit messages (or at least the merge that
|
83 | brings them into `master`) must follow the
|
84 | [AngularJS commit guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) with a special format such as `feat: describe new feature`
|
85 | in order for the releasing to occur and for the described items to be added
|
86 | to the release notes.
|