bvanderlaan/CONTRIBUTING.md

## CONTRIBUTING.md

      
    Raw
  

              CONTRIBUTING.md
            
          
    Contributing to <insert project name here>

First Thanks for helping out 👍🎉 we really appreciate it 🎉👍
The following is a set of guidelines for contributing to the project. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
Pull Requests

All Pull Requests are welcome but to ensure they get committed please make sure you include the following in your PR:

Brief description of the issue
Results from the automated tests
Ensure that tests are updated or new tests are added to properly cover the change in question
Impacted areas of application for test focus
If dependencies on another PR, include a reference number and describe the dependency
End all files with a newline!

Style guides

Git Commit Messages


Use the imperative mood ("Add feature" not "Added feature", "Move cursor to..." not "Moves cursor to...")
Limit the first line to 72 characters or less
Limit each line in the body of the commit to 80 characters or less
Reference issues and pull requests liberally after the first line
When only changing documentation, include [ci skip] in the commit description
Consider starting the commit message with an applicable emoji:

🎨 :art: when improving the format/structure of the code
🐎 :racehorse: when improving performance
🚱 :non-potable_water: when plugging memory leaks
📝 :memo: when writing docs
🐧 :penguin: when fixing something on Linux
🍎 :apple: when fixing something on macOS
🏁 :checkered_flag: when fixing something on Windows
🐛 :bug: when fixing a bug
🔥 :fire: when removing code or files
💚 :green_heart: when fixing the CI build
✅ :white_check_mark: when adding tests
🔒 :lock: when dealing with security
⬆️ :arrow_up: when upgrading dependencies
⬇️ :arrow_down: when downgrading dependencies
👕 :shirt: when removing linter warnings


JavaScript

All JavaScript must adhere to The JavaScript Style Guide.
Special Considerations


Prefer the object spread operator ({...anotherObj}) to Object.assign()
Prefer the array spread operator ([...array]) to Array.concat()
Prefer array destruction in promises (.then(([a, b, c]) => {..})) to non-standard .spread((a, b, c) => {..})
Prefer Arrow Functions (() => console.log('hello')) to named or anonymous functions (function() { console.log('world'); })
Prefer Class syntax vs. function constructors/Prototype
Inline exports with expressions whenever possible
// Use this:
module.exports = {
  property1: 'hello world',
  myFunction() {..}
};

// Instead of:
const Lib = {
  property1: 'hello world',
  myFunction() {..}
}

module.exports = Lib

Prefer named exports vs. default exports in order to support tree shaking (const { ClassName } = require('my-module');)
// Use this:
class ClassName {
}

module.exports = {
  ClassName,
};

// Instead of:
module.exports = class ClassName {
}

Place requires in the following order:

Built in Node Modules (such as path)
NPM Modules (such as sinon-chai)
Local Modules (using relative paths)


Sort all requires in alphabetical order. For local modules sort first by path followed by file name.

✅Good Example

// good
const b = require('./b');
const c = require('./c');
const a = require('../lib/a');
❌Bad Example

// bad
const a = require('../lib/a');
const c = require('./c');
const b = require('./b');
Tests


Include thoughtfully-worded, well-structured Mocha tests in the ./test folder.

The ./test folder structure should mimic the production folder (i.e. ./src)


Tests should be categorized as Unit, Integration, System, and Benchmark. To allow for easy glob patterns mark unit tests with the *.unit.js extension, integration tests with the *.integration.js extension, System tests with *.system.js extension and Benchmark tests with the *.bench.js extension.
The test file should have the same name as the production file it is testing say for the proper file extension (i.e. *.unit.js, *.system.js)
Testing private functions is discouraged. Needing to test a private function is usually an indication that your service has too many responsibilities and should be split up.
Tests should use arrow functions and should never use this
Tests should be using the sinon-chai expectations for consistency paired with chai-as-promised

Please see the helpful notes here around testing promises


Tests must follow the pattern setup - run - assert - destroy, a describe should still work if it is marked as .only
Treat describe as a noun or situation.
Treat it as a statement about state or how an operation should change state.

✅Good Example

describe('GET User Route', () => {
  describe('when user found', () => {
    it('should return 200', () => {...});
    it('should return the user object', () => {...});
  });
  describe('when user not found', () => {
    it('should return 404', () => {...});
  });
});
❌Bad Example

describe('GET User Route', () => {
  it('when user found return 200', () => {...});
  it('when user not found return 404', () => {...});
  it('when user found return the user object', () => {...});
});
Additional Notes

Git Branches


Branch names should be all lower case. This avoids communication issues when multiple people need to access the same branch, Check out proj 1234 is that Proj-1234, proj-1234 or PROJ-1234, and also prevents accidental duplication; branch proj-1234 is not the same as Proj-1234 but both can exist. Sticking to lower case saves on confusion.
Branch names should be under 50 characters. This makes checking them out and using various git commands easier: less typing.
Branch names should use kebab case (snake case but use dash - instead of underscore _). A dash stands out more and is not lost by an underline; also to type a dash you only need to push one key.
Branch names ideally should include a description of the change to make it easier to know what each branch does without having to look up each issue. The description should be as short as possible.

✅Great Example: proj-1234-type-error-on-update
☑️Good Example: type-error-on-update
❌Bad Example: this-fixes-a-type-error-on-update
❌Horrible Example: Fixes_typeError_on-update
No results found