87 lines
3.7 KiB
Markdown
87 lines
3.7 KiB
Markdown
|
# CONTRIBUTING to eslint-plugin-jsdoc
|
||
|
|
|
||
|
|
## Testing changes locally
|
||
|
|
|
||
|
|
You might try a TDD approach and add tests within the `test` directory,
|
||
|
|
to try different configs, you may find it easier to try out changes in
|
||
|
|
a separate local directory.
|
||
|
|
|
||
|
|
You can run [`npm link`](https://docs.npmjs.com/cli/link) for this purpose,
|
||
|
|
pointing from your project to this project. For example, while in your project
|
||
|
|
root and with `eslint-plugin-jsdoc` as a sibling, run:
|
||
|
|
|
||
|
|
```shell
|
||
|
|
npm link ../eslint-plugin-jsdoc
|
||
|
|
```
|
||
|
|
|
||
|
|
## Building the project
|
||
|
|
|
||
|
|
After running `npm install` to get the latest dependencies and devDependencies,
|
||
|
|
you can run the following command to update the `dist` files, with `dist/index.js`
|
||
|
|
being the `main` entrance point from `package.json`:
|
||
|
|
|
||
|
|
```shell
|
||
|
|
npm run build
|
||
|
|
```
|
||
|
|
|
||
|
|
## Coding standards
|
||
|
|
|
||
|
|
The project follows ESLint rules from [`canonical`](https://www.npmjs.com/package/eslint-config-canonical)
|
||
|
|
and testing follows its subconfig, `canonical/mocha`.
|
||
|
|
|
||
|
|
## Testing
|
||
|
|
|
||
|
|
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
|
||
|
|
`test/rules/index.js`.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
`parserOptions` will be `ecmaVersion: 6` by default, but tests can override `parserOptions`
|
||
|
|
with their own.
|
||
|
|
|
||
|
|
See ESLint's [RuleTester](https://eslint.org/docs/developer-guide/nodejs-api#ruletester)
|
||
|
|
for more on the allowable properties (e.g., `code`, `errors` (for invalid rules),
|
||
|
|
`options`, `settings`, etc.).
|
||
|
|
|
||
|
|
Note that besides `npm test`, there is `npm run test-cov` which shows more
|
||
|
|
detailed information on coverage. Coverage should be maintained at 100%, and
|
||
|
|
if there are a few guards in place for future use, the code block in question
|
||
|
|
can be ignored by being preceded by `/* istanbul ignore next */` (including
|
||
|
|
for warnings where the block is never passed over (i.e., the block is always
|
||
|
|
entered)). If you want to test without coverage at all, you can use
|
||
|
|
`npm run test-no-cov`. To only test rules rather than other files, you
|
||
|
|
can use `npm run test-index`.
|
||
|
|
|
||
|
|
To test specific rules, you can supply a comma-separated list with the `--rule`
|
||
|
|
flag passed to `test-index`, e.g., for `check-examples` and `require-example`:
|
||
|
|
|
||
|
|
`npm run --rule=check-examples,require-example test-index`.
|
||
|
|
|
||
|
|
You can further limit this by providing `--invalid` and/or `--valid` flags
|
||
|
|
with a comma-separated list of 0-based indexes that you wish to include (also
|
||
|
|
accepts negative offsets from the end, e.g., `-1` for the last item). For
|
||
|
|
example, to check the first and third invalid tests of `check-examples`
|
||
|
|
alon with the second valid test, you can run:
|
||
|
|
|
||
|
|
`npm run --rule=check-examples --invalid=0,2 --valid=1 test-index`.
|
||
|
|
|
||
|
|
## Requirements for PRs
|
||
|
|
|
||
|
|
PRs should be mergeable, [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
|
||
|
|
first against the latest `master`.
|
||
|
|
|
||
|
|
The number of commits will ideally be limited in number, unless extra commits
|
||
|
|
can better show a progression of features.
|
||
|
|
|
||
|
|
Commit messages should be worded clearly and the reason for any PR made clear
|
||
|
|
by linking to an issue or giving a full description of what it achieves.
|
||
|
|
|
||
|
|
## Merging
|
||
|
|
|
||
|
|
We use [semantic-release](https://github.com/semantic-release/semantic-release)
|
||
|
|
for preparing releases, so the commit messages (or at least the merge that
|
||
|
|
brings them into `master`) must follow the
|
||
|
|
[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`
|
||
|
|
in order for the releasing to occur and for the described items to be added
|
||
|
|
to the release notes.
|