bug 1523104: remote: salvage some code style documentation from Marionette; r=me
authorAndreas Tolfsen <ato@sny.no>
Sun, 17 Feb 2019 15:39:48 +0000
changeset 521090 6ee3f621e6b8
parent 521089 705a560085d4
child 521091 d4ddf649862b
push id10862
push userffxbld-merge
push dateMon, 11 Mar 2019 13:01:11 +0000
treeherdermozilla-beta@a2e7f5c935da [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersme
bugs1523104
milestone67.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
bug 1523104: remote: salvage some code style documentation from Marionette; r=me
remote/doc/CodeStyle.md
remote/doc/index.rst
new file mode 100644
--- /dev/null
+++ b/remote/doc/CodeStyle.md
@@ -0,0 +1,73 @@
+Style guide
+===========
+
+Like other projects, we also have some guidelines to keep to the code.
+For the overall remote agent project, a few rough rules are:
+
+  * Make your code readable and sensible, and don’t try to be
+    clever.  Prefer simple and easy solutions over more convoluted
+    and foreign syntax.
+
+  * Fixing style violations whilst working on a real change as a
+    preparatory clean-up step is good, but otherwise avoid useless
+    code churn for the sake of conforming to the style guide.
+
+  * Code is mutable and not written in stone.  Nothing that
+    is checked in is sacred and we encourage change to make
+    this a pleasant ecosystem to work in.
+
+  * We never land any code that is unnecessary or unused.
+
+
+Documentation
+-------------
+
+We keep our documentation (what you are reading right now!) in-tree
+under [remote/doc].  Updates and minor changes to documentation should
+ideally not be scrutinised to the same degree as code changes to
+encourage frequent updates so that documentation does not go stale.
+To that end, documentation changes with `r=me a=doc` from anyone
+with commit access level 3 are permitted.
+
+Use fmt(1) or an equivalent editor specific mechanism (such as
+<kbd>Meta-Q</kbd> in Emacs) to format paragraphs at a maximum of
+75 columns with a goal of roughly 65.  This is equivalent to `fmt
+-w75 -g65`, which happens to the default on BSD and macOS.
+
+The documentation can be built locally this way:
+
+	% ./mach doc remote
+
+[remote/doc]: https://searchfox.org/mozilla-central/source/remote/doc
+
+
+Linting
+-------
+
+The remote agent consists mostly of JavaScript code, and we lint that
+using [mozlint], which is harmonises different linters including [eslint].
+
+To run the linter and get sensible output:
+
+	% ./mach lint -funix remote
+
+For certain classes of style violations, eslint has an automatic
+mode for fixing and formatting code.  This is particularly useful
+to keep to whitespace and indentation rules:
+
+	% ./mach eslint --fix remote
+
+The linter is also run as a try job (shorthand `ES`) which means
+any style violations will automatically block a patch from landing
+(if using Autoland) or cause your changeset to be backed out (if
+landing directly on inbound).
+
+If you use git(1) you can [enable automatic linting] before
+you push to a remote through a pre-push (or pre-commit) hook.
+This will run the linters on the changed files before a push and
+abort if there are any problems.  This is convenient for avoiding
+a try run failing due to a simple linting issue.
+
+[mozlint]: /tools/lint/usage.html
+[eslint]: https://eslint.org/
+[enable automatic linting]: https://firefox-source-docs.mozilla.org/tools/lint/usage.html#using-a-vcs-hook
--- a/remote/doc/index.rst
+++ b/remote/doc/index.rst
@@ -15,16 +15,17 @@ and debug JavaScript execution.
 
 .. toctree::
   :maxdepth: 1
 
   Building.md
   Debugging.md
   Testing.md
   Prefs.md
+  CodeStyle.md
 
 
 Bugs
 ====
 
 Bugs are tracked under the `Remote Protocol`_ product.
 
 .. _Remote Protocol: https://bugzilla.mozilla.org/describecomponents.cgi?product=Remote%20Protocol