UNPKG

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