Contributing to this Project

Here's how you can help.

Process

In the spirit of openness, this project follows the Forking Flow, a derivative of the Gitflow model. We use Pull Requests to develop conversations around ideas, and turn ideas into actions.

Some PR Basics

• Anyone can submit a Pull Request with changes they'd like to see made.
• Pull Requests should attempt to solve a single [1], clearly defined problem [2].
• Everyone should submit Pull Requests early (within the first few commits), so everyone on the team is aware of the direction you're taking.
• Authors are responsible for explicitly tagging anyone who might be impacted by the pull request and get the recipient's sign-off [3].
• The Pull Request should serve as the authority on the status of a change, so everyone on the team is aware of the plan of action.
• Relevant domain authority must sign-off on a pull request before it is merged [4].
• Anyone except the author can merge a pull request once all sign-offs are complete.

[1]: if there are multiple problems you're solving, it is recommended that you create a branch for each. For example, if you are implementing a small change and realize you want to refactor an entire function, you might want to implement the refactor as your first branch (and pull request), then create a new branch (and pull request) from the refactor to implement your new feature. This helps resolve merge conflicts and separates out the logical components of the decision-making process.
[2]: include a description of the problem that is being resolved in the description field, or a reference to the issue number where the problem is reported. Examples include; "Follow Button doesn't Reflect State of Follow" or "Copy on Front-page is Converting Poorly".
[3]: notably, document the outcome of any out-of-band conversations in the pull request.
[4]: changes to marketing copy, for example, must be approved by the authority on marketing.

Coding Conventions

Detail and examples below; here are the basic principles.

tl;dr

• 2 spaces, no tabs.
• elide (remove) any trailing whitespace, except for formatting purposes in Jade.
• use leading comma syntax for long lists (> 3).
• vertically align logically similar items.
• curly brace on the same line as the statement.
• always use semicolons and braces; even though they're [sometimes] optional, focus on clarity.

Examples

Trailing Whitespace

You should remove whitespace at the end of lines. For example;

...should be reduced to:

The only exception is in Jade, when a single space character is inserted into the HTML document using the | prefix.

This allows, among other things, the enduser to copy-paste blocks of text that might include various types of elements without breaking formatting.

Leading Comma

To increase readability and reduce errors, we use the leading comma syntax when lists grow longer than 3 items in length.

This list of directives has the comma at the end of each line:

...but should be reformatted to:

Curly Braces

Put your curly braces on the same line as the logical statement that requires them:

...should be:

Always include curly braces, even though Javascript has some cases where you can exclude them: ...should be:

For brevity in cases like this, you can reduce it to a single line, but keep your curly braces:

Vertical Alignment

Logically similar blocks should be made visually pleasing where possible.

For example, without inserting any spaces to vertically align blocks:

...is much more readible when presented as follows:

For a more in-depth guide to NodeJS conventions, you can use Felix's Node Styleguide.