|
| 1 | +# Contributing |
| 2 | + |
| 3 | +First off, thanks for taking the time to contribute! |
| 4 | + |
| 5 | +The following is a set of guidelines for contributing to this project. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. |
| 6 | + |
| 7 | +#### Table Of Contents |
| 8 | + |
| 9 | +* [Code of Conduct](#code-of-conduct) |
| 10 | +* [Project governance](#project-governance) |
| 11 | + * [Rules](#rules) |
| 12 | + * [Releases](#releases) |
| 13 | + * [Changes to this arrangement](#changes-to-this-arrangement) |
| 14 | +* [Pull Requests](#pull-requests) |
| 15 | +* [Styleguides](#styleguides) |
| 16 | + * [Git Commit Messages](#git-commit-messages) |
| 17 | + * [JavaScript Styleguide](#javascript-styleguide) |
| 18 | + * [Tests Styleguide](#tests-styleguide) |
| 19 | +* [Developer's certificate of origin](#developers-certificate-of-origin) |
| 20 | + |
| 21 | +## Code of Conduct |
| 22 | + |
| 23 | +This project and everyone participating in it is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. |
| 24 | + |
| 25 | +## Project Governance |
| 26 | + |
| 27 | +Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. |
| 28 | + |
| 29 | +### Rules |
| 30 | + |
| 31 | +There are a few basic ground-rules for contributors: |
| 32 | + |
| 33 | +1. **No `--force` pushes** or modifying the Git history in any way. |
| 34 | +2. **All modifications** should be subject to a **pull request** to solicit feedback from other contributors. The base branch of the pull request should be the "release" branch. All issues should be merged into it until is ready to declare a formal release. |
| 35 | + |
| 36 | +### Releases |
| 37 | + |
| 38 | +Declaring formal releases remains the prerogative of the project maintainer. |
| 39 | + |
| 40 | +### Changes to this arrangement |
| 41 | + |
| 42 | +This document may also be subject to pull-requests or changes by contributors where you believe you have something valuable to add or change. |
| 43 | + |
| 44 | +## Pull Requests |
| 45 | + |
| 46 | +* Fill in [the required template](PULL_REQUEST_TEMPLATE.md). |
| 47 | +* Do not include issue numbers in the PR title. |
| 48 | +* Follow the [JavaScript styleguide](#javascript-styleguide). |
| 49 | +* Follow the [Tests styleguide](#tests-styleguide). |
| 50 | +* All enhancements and bug fixes must be accompanied with all needed new related regression test. |
| 51 | +* Coverage of unit tests must remain 100%. |
| 52 | +* Run tests often. Tests are ran automatically with Travis when you push, but you still need to run them locally before pushing. |
| 53 | +* Document new features, or update documentation if changes affect to it. |
| 54 | +* End all files with a newline. |
| 55 | +* Place requires in the following order: |
| 56 | + * Built in Node Modules (such as `path`) |
| 57 | + * NPM Modules (such as `lodash`) |
| 58 | + * Local Modules (using relative paths) |
| 59 | + |
| 60 | +## Styleguides |
| 61 | + |
| 62 | +### Git Commit Messages |
| 63 | + |
| 64 | +* Use the present tense ("Add feature" not "Added feature") |
| 65 | +* Use the imperative mood ("Move cursor to..." not "Moves cursor to...") |
| 66 | +* Limit the first line to 72 characters or less |
| 67 | +* Reference issues and pull requests liberally after the first line |
| 68 | + |
| 69 | +### JavaScript Styleguide |
| 70 | + |
| 71 | +All JavaScript must adhere to the style defined in the `.eslintrc.json` file. |
| 72 | + |
| 73 | +### Tests Styleguide |
| 74 | + |
| 75 | +- Fail tests first. How do you know if it is actually testing anything if the assert never failed? |
| 76 | +- Treat `describe` as a noun or situation (Situations usually start with "when"). |
| 77 | +- Treat `it` as a statement about state or how an operation changes state. Usually, all `it` should start with "should". |
| 78 | +- Prefer fewer asserts per `it`. |
| 79 | +- Prefer one file for all specs of a javascript file, but, if it grows too much, split it into many files adding a sufix describing the behavior being tested in it (`file.behavior.js`) |
| 80 | + |
| 81 | +#### Example |
| 82 | + |
| 83 | +```js |
| 84 | +describe("a dog", () => { |
| 85 | + describe("when is happy", () => { |
| 86 | + it("should wags its tail", () => { |
| 87 | + expect(dog.tail.moving).to.be.true(); |
| 88 | + }); |
| 89 | + }); |
| 90 | +}); |
| 91 | +``` |
| 92 | + |
| 93 | +## Developer's Certificate of Origin |
| 94 | + |
| 95 | +By making a contribution to this project, I certify that: |
| 96 | + |
| 97 | +- (a) The contribution was created in whole or in part by me and I have the right to |
| 98 | + submit it under the open source license indicated in the file; or |
| 99 | + |
| 100 | +- (b) The contribution is based upon previous work that, to the best of my knowledge, is |
| 101 | + covered under an appropriate open source license and I have the right under that license |
| 102 | + to submit that work with modifications, whether created in whole or in part by me, under |
| 103 | + the same open source license (unless I am permitted to submit under a different |
| 104 | + license), as indicated in the file; or |
| 105 | + |
| 106 | +- (c) The contribution was provided directly to me by some other person who certified |
| 107 | + (a), (b) or (c) and I have not modified it. |
| 108 | + |
| 109 | +- (d) I understand and agree that this project and the contribution are public and that a |
| 110 | + record of the contribution (including all personal information I submit with it, |
| 111 | + including my sign-off) is maintained indefinitely and may be redistributed consistent |
| 112 | + with this project or the open source license(s) involved. |
0 commit comments