1 | # Contributing to Bedrock
|
2 |
|
3 | Details for developers about contributing to the Bedrock code.
|
4 |
|
5 | ## Commit Messages
|
6 |
|
7 | When 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 |
|
17 | Example commit messages:
|
18 |
|
19 | ```
|
20 | Add 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 |
|
25 | Addresses #123.
|
26 | ```
|
27 |
|
28 | ```
|
29 | Fix memory leak in animation runner.
|
30 |
|
31 | When canceling an animation, a closure was created that had a reference
|
32 | to a DOM element that caused it to be held indefinitely in jquery's cache.
|
33 | The closure has been reworked to avoid the reference.
|
34 |
|
35 | Addresses #124.
|
36 | ```
|
37 |
|
38 | ## ChangeLogs
|
39 |
|
40 | Packages 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 |
|
54 | Follow these rules as strictly as possible; only stray if there's a Very Good
|
55 | Reason 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 |
|
111 | If an arrow function will all fit on one line, do it:
|
112 |
|
113 | ```js
|
114 | someLongFunctionOrExpression(
|
115 | a, b,
|
116 | (some, long, params) => someExpression());
|
117 | ```
|
118 |
|
119 | If it won't fit on one line, then break after the arrow:
|
120 |
|
121 | ```js
|
122 | someLongFunctionOrExpression(
|
123 | a, b, (some, long, params, tooManyParams) =>
|
124 | someExpressionThatIsJustTooLong());
|
125 | ```
|
126 |
|
127 | #### Linter
|
128 |
|
129 | A number of style and code rules can be checked with [ESLint](https://eslint.org/).
|
130 |
|
131 | $ npm run lint
|
132 |
|
133 |
|
134 | ### AngularJS
|
135 |
|
136 | See [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 |
|
144 | The 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
|