UNPKG

5.48 kBMarkdownView Raw
1# Contributing to Bedrock
2
3Details 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
13Example commit messages:
14
15```
16Add 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
21Addresses #123.
22```
23
24```
25Fix memory leak in animation runner.
26
27When canceling an animation, a closure was created that had a reference
28to a DOM element that caused it to be held indefinitely in jquery's cache.
29The closure has been reworked to avoid the reference.
30
31Addresses #124.
32```
33
34## Code Style
35
36### JavaScript
37
38Follow these rules as strictly as possible; only stray if there's a Very Good
39Reason 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
94If an arrow function will all fit on one line, do it:
95
96```js
97someLongFunctionOrExpression(
98 a, b,
99 (some, long, params) => someExpression());
100```
101
102If it won't fit on one line, then break after the arrow:
103
104```js
105someLongFunctionOrExpression(
106 a, b, (some, long, params, tooManyParams) =>
107 someExpressionThatIsJustTooLong());
108```
109
110#### Linter
111
112A 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
121See [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
129The 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