CONTRIBUTING.md 4.33 KB
Newer Older
1 2
# RTV.js Contributions

3
Thank you for considering a contribution to RTV.js!
4

5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
## Development

Local development is straightforward. Use the following versions of Node.js and npm:

*   Node.js: `>=10.11.0`
*   npm: `>=6.4.1`

Install all project dependencies:

```bash
$ npm install
```

The following npm commands will get you started:

*   `build`: Builds the library, outputs to `/dist`
*   `docs`: Builds the API documentation, _overwritting_ `/API.md`
*   `test`: Runs all unit tests and linting.
*   `test:unit`: Runs unit tests only.
*   `test:unit:watch`: Runs unit tests in watch mode, re-running tests as you make changes to code.
*   `test:unit:debug`: Runs unit tests in debug mode so you can step through code.
    *   Use Mocha's `describe.only()` and `it.only()` helpers to isolate the test you want to debug, but be sure to remove them when you're done, otherwise coverage will fail.
*   `test:coverage`: Checks for code coverage after running unit tests, outputs to `/coverage`
*   `lint`: Checks the code for lint.
29 30
*   `start`: Builds the library, starts Node.js in debug mode (with `--inspect`), and automatically loads the library into the global environment as `rtv` (along with `lodash` as `ld`, and `Object.prototype.toString` as `ostr`) by running the following script: `/tools/node.js`
*   `html`: Builds the library and starts `live-server` at http://localhost:8080 with a root of `/tools` where you can load any of the HTML files in that directory to manually test the build in a browser: [UMD](http://localhost:8080/rtvjs-umd.html) or [ESM](http://localhost:8080/rtvjs-esm.html).
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49

See `/package.json` scripts for other commands.

## Pre-commit Scripts

`npm install` will configure a pre-commit hook, for this repository, that will perform these steps when you attempt to commit to your local repository:

*   Check the code for lint.
*   Build the API documentation and add `/API.md` to your commit if there were any changes.

## Best Practices

*   Use [JSDoc](http://usejsdoc.org/) syntax for __ALL__ function and class comments.
    *   Name internal functions with an underscore prefix (e.g. `_foo()`).
    *   Add a leading `[Internal]` prefix in the comment's description block.
    *   Include the JSDoc `@private` directive.
*   Favor `function() {}` over arrow functions unless contextual binding is required.
*   Use the latest standardized ES syntax.
*   Avoid using syntax that is still under active proposal.
Stefan Cameron's avatar
Stefan Cameron committed
50 51 52 53

## Merge Requests

In general, once your merge request is posted, you can expect one of the maintainers to respond to it within a few business days.
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79

### Template

Please use this template when filing merge requests:

```markdown
### Description

Include a summary of the change and which issue is fixed.

If a feature is being implemented, explain your motivation for it. If a bug is being fixed, explain steps to reproduce it.

List any new dependencies that are required for this change and why they are needed (if it isn't obvious).

### Type of change

Place an X in all relevant options and delete those that aren't, along with this note.

- [] Bug fix (non-breaking change which fixes an issue)
- [] New feature (non-breaking change which adds functionality)
- [] Breaking change (fix or feature that would cause existing functionality to no longer work as expected)

### Checklist

Place an X in all relevant checks and delete those that aren't, along with this note.

Stefan Cameron's avatar
Stefan Cameron committed
80
- [] I have added this change under an appropriate heading in the `[Unreleased]` section of the `/CHANGELOG.md`
81 82 83 84
- [] My code builds (verified with `npm run build`)
- [] My code follows the style guidelines of this project (verified with `npm run lint`)
- [] I have performed a self-review of my own code
- [] I have commented my code, particularly in hard-to-understand areas
Stefan Cameron's avatar
Stefan Cameron committed
85 86
- [] I have made corresponding changes to the documentation, including the `/README.md`
- [] I have verified my changes to the API documentation in `/API.md` (cross-reference links in particular, verified _in part_ with `npm run docs`)
87 88 89 90 91 92
- [] My changes generate no new warnings or errors (verified with `npm test`)
- [] I have added tests that prove my fix is effective or that my feature works
- [] New and existing unit tests pass locally with my changes
- [] Test coverage has not decreased in my branch as a result of my additions
- [] Any prerequisite changes have already been merged and published in upstream modules
```