4 Like other projects, we also have some guidelines to keep to the code.
5 For the overall Remote Agent project, a few rough rules are:
7 * Make your code readable and sensible, and don’t try to be
8 clever. Prefer simple and easy solutions over more convoluted
11 * Fixing style violations whilst working on a real change as a
12 preparatory clean-up step is good, but otherwise avoid useless
13 code churn for the sake of conforming to the style guide.
15 * Code is mutable and not written in stone. Nothing that
16 is checked in is sacred and we encourage change to make
17 this a pleasant ecosystem to work in.
19 * We never land any code that is unnecessary or unused.
25 We keep our documentation (what you are reading right now!) in-tree
26 under [remote/doc]. Updates and minor changes to documentation should
27 ideally not be scrutinised to the same degree as code changes to
28 encourage frequent updates so that documentation does not go stale.
29 To that end, documentation changes with `r=me a=doc` from anyone
30 with commit access level 3 are permitted.
32 Use fmt(1) or an equivalent editor specific mechanism (such as
33 <kbd>Meta-Q</kbd> in Emacs) to format paragraphs at a maximum of
34 75 columns with a goal of roughly 65. This is equivalent to `fmt
35 -w75 -g65`, which happens to the default on BSD and macOS.
37 The documentation can be built locally this way:
41 [remote/doc]: https://searchfox.org/mozilla-central/source/remote/doc
47 The Remote Agent consists mostly of JavaScript code, and we lint that
48 using [mozlint], which is harmonises different linters including [eslint].
50 To run the linter and get sensible output:
52 % ./mach lint -funix remote
54 For certain classes of style violations, eslint has an automatic
55 mode for fixing and formatting code. This is particularly useful
56 to keep to whitespace and indentation rules:
58 % ./mach eslint --fix remote
60 The linter is also run as a try job (shorthand `ES`) which means
61 any style violations will automatically block a patch from landing
62 (if using Autoland) or cause your changeset to be backed out (if
63 landing directly on inbound).
65 If you use git(1) you can [enable automatic linting] before
66 you push to a remote through a pre-push (or pre-commit) hook.
67 This will run the linters on the changed files before a push and
68 abort if there are any problems. This is convenient for avoiding
69 a try run failing due to a simple linting issue.
71 [mozlint]: /tools/lint/usage.html
72 [eslint]: https://eslint.org/
73 [enable automatic linting]: https://firefox-source-docs.mozilla.org/tools/lint/usage.html#using-a-vcs-hook