1 | # Contributing to Bedrock
|
2 |
|
3 | Details for developers about contributing to the Bedrock code.
|
4 |
|
5 | ## Commit Messages
|
6 |
|
7 | * Use present tense, so it's read as: If you applied this changeset, X will happen.
|
8 | * Start with a capital letter; use proper capitalization throughout, end with a period.
|
9 | * Keep the first message under 50 chars if possible, (certainly under 80). It should express a basic summary of the changeset. Be specific, don't just say "Fix the bug."
|
10 | * If you have more to express after the summary, leave an empty line after the opening summary and then express whatever you need in an extended description.
|
11 | * If you need to reference issues, then after the optional extended description, leave an empty line and then use `Addresses #issue-number` (for example).
|
12 |
|
13 | Example commit messages:
|
14 |
|
15 | ```
|
16 | Add infinite scroll to comment section.
|
17 |
|
18 | - Replaces existing pagination mechanism with an infinite scroll feature.
|
19 | - Future work includes CSS-animated fireworks when new comments arrive.
|
20 |
|
21 | Addresses #123.
|
22 | ```
|
23 |
|
24 | ```
|
25 | Fix memory leak in animation runner.
|
26 |
|
27 | When canceling an animation, a closure was created that had a reference
|
28 | to a DOM element that caused it to be held indefinitely in jquery's cache.
|
29 | The closure has been reworked to avoid the reference.
|
30 |
|
31 | Addresses #124.
|
32 | ```
|
33 |
|
34 | ## Code Style
|
35 |
|
36 | ### JavaScript
|
37 |
|
38 | Follow these rules as strictly as possible; only stray if there's a Very Good
|
39 | Reason To (TM).
|
40 |
|
41 | * Two-space indentation, NO tabs.
|
42 | * Same-line curly brackets, keep else/elseif/catch/while on the same line
|
43 | as a related opening bracket; put one space before opening brackets.
|
44 | * No extra spaces after if, while, etc. before the parenthetical.
|
45 | * Use semicolons.
|
46 | * Use camelCase for variables, method names, etc. Only use underscores as a
|
47 | prefix for "private" functions or variables that really need to be
|
48 | distinguished as such.
|
49 | * Return early and avoid else if possible.
|
50 | * Use continuation-passing-style (callbacks) when writing node.js code as
|
51 | it is popular practice there. Use Promises in client-side code. If Promises
|
52 | and other generator-related tech begin to become popular in node.js then
|
53 | we will switch to that. We want our code to be as compatible as possible
|
54 | with the community and idiomatic in the environments in which it is run.
|
55 | * Use async for callback management: [https://github.com/caolan/async]()
|
56 | * Prefer single quotes for strings. Only use double quotes when it would
|
57 | result in fewer escape sequences. If there's any HTML that must be written
|
58 | in a JS-string, it will be easier with single-quotes as you won't have
|
59 | to escape any the HTML double quoting.
|
60 | * Prefer one variable declaration per line, no elaborate indentation, and
|
61 | declare nearest to where variables are used. You may declare simple iterator
|
62 | vars for loops multiple times in the same function, functional-scope
|
63 | notwithstanding.
|
64 | * Do not use trailing commas (for example: [foo, bar,]).
|
65 | * Line break at 80 chars; if you must line break for function parameters, line
|
66 | break at the opening parenthesis and move all parameters down, do not
|
67 | break in the middle of the parameter list. The only exception to this is
|
68 | if a parameter is an object with too many properties to fit on a single
|
69 | line; you may break after the opening object bracket for this. Break before
|
70 | periods for chaining function calls.
|
71 | * When writing backend (node.js) code, use ES2016+, when writing frontend
|
72 | code (browser) use ES5.
|
73 | * When writing arrow functions (`=>`), if they can be kept on a single
|
74 | line, do so. Functions are just mappings from x to y (or `x => y`); it
|
75 | is easier to read when they are short and on a single line. If the
|
76 | function is longer (or requires curly braces `{`), break after the
|
77 | arrow. See examples.
|
78 | * Avoid getters and setters.
|
79 | * Do not override built-in prototypes unless you're fixing IE.
|
80 | * If you find a need to use OOP, use PascalCase for classes. Avoid OOP unless
|
81 | there's a really good justification for the added complexity. OOP is not a
|
82 | panacea, it is a tool for a very specific problem set. If it is used for
|
83 | a problem that is not in that set, there are only disadvantages. Examples
|
84 | include, but are not limited to: unused layers of abstraction and overhead
|
85 | that affect both runtime and development time, more indirection that must
|
86 | be traced during debugging, decreased ratio of effectual code lines to lines
|
87 | of code, and stacktrace horrors.
|
88 | * See: http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html
|
89 |
|
90 | #### Examples
|
91 |
|
92 | ##### Arrow functions:
|
93 |
|
94 | If an arrow function will all fit on one line, do it:
|
95 |
|
96 | ```js
|
97 | someLongFunctionOrExpression(
|
98 | a, b,
|
99 | (some, long, params) => someExpression());
|
100 | ```
|
101 |
|
102 | If it won't fit on one line, then break after the arrow:
|
103 |
|
104 | ```js
|
105 | someLongFunctionOrExpression(
|
106 | a, b, (some, long, params, tooManyParams) =>
|
107 | someExpressionThatIsJustTooLong());
|
108 | ```
|
109 |
|
110 | #### Linter
|
111 |
|
112 | A number of style and code rules can be checked with
|
113 | [jshint](http://jshint.com/) and [jscs](https://github.com/jscs-dev/node-jscs):
|
114 |
|
115 | $ grunt jshint
|
116 | $ grunt jscs
|
117 |
|
118 |
|
119 | ### AngularJS
|
120 |
|
121 | See [bedrock-angular](https://github.com/digitalbazaar/bedrock-angular/blob/master/CONTRIBUTING.md).
|
122 |
|
123 |
|
124 | ## Testing
|
125 |
|
126 | * Backend tests are typically written using the mocha framework.
|
127 | * Frontend tests are typically written using protractor to test a web browser.
|
128 |
|
129 | The following projects are used for creating tests:
|
130 |
|
131 | * https://github.com/admc/wd
|
132 | * http://visionmedia.github.io/mocha/
|
133 | * http://chaijs.com/
|
134 | * https://github.com/domenic/chai-as-promised
|