--- a/testing/geckodriver/CONTRIBUTING.md
+++ b/testing/geckodriver/CONTRIBUTING.md
@@ -1,97 +1,227 @@
-# Contributing to geckodriver
+Contributing
+============
-The geckodriver project welcomes contributions from everyone. There are a
-number of ways you can help:
+We are delighted that you want to help improve geckodriver!
+Mozilla’s WebDriver implementation consists of a few different
+parts it can be useful to know about:
+
+ * [_geckodriver_] provides the HTTP API described by the [WebDriver
+ protocol] to communicate with Gecko-based browsers such as
+ Firefox and Fennec. It is a standalone executable written in
+ Rust, and can be used with compatible W3C WebDriver clients.
-## Issue Reports
+ * [_Marionette_] is the Firefox remote protocol used by geckodriver
+ to communicate with, instrument, and control Gecko. It is
+ built in to Firefox and written in [XPCOM] flavoured JavaScript.
-When opening new issues or commenting on existing issues please make
-sure discussions are related to concrete technical issues with the
-geckodriver or Marionette software.
+ * [_libwebdriver_] is a Rust crate providing interfaces, traits
+ and types, errors, type- and bounds checks, and JSON marshaling
+ for correctly parsing and emitting the [WebDriver protocol].
+
+By participating in this project, you agree to abide by the Mozilla
+[Community Participation Guidelines]. Here are some guidelines
+for contributing high-quality and actionable bugs and code.
-For issue reports to be actionable, it must be clear exactly what the
-observed and expected behaviours are, and how to set up the state required
-to observe the erroneous behaviour. The most useful thing to provide is a
-minimal HTML file which allows the problem to be reproduced, plus a
-trace-level log from geckodriver showing the wire-protocol calls used to set
-up the problem. Please provide [concise reproducible test
-cases](http://sscce.org/) and describe what results you are seeing and what
-results you expect. Because of the wide variety of client bindings for
-WebDriver, clients scripts and logs are typically not very useful if the
-verbose geckodriver logs are available. Issues relating to a specific client
-should be filed in the issue tracker of that project.
+[_geckodriver_]: ./README.md
+[_Marionette_]: ../marionette/README.md
+[_libwebdriver_]: ../webdriver/README.md
+[WebDriver protocol]: https://w3c.github.io/webdriver/webdriver-spec.html#protocol
+[XPCOM]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Guide
+[Community Participation Guidelines]: https://www.mozilla.org/en-US/about/governance/policies/participation/
+
+
+Reporting bugs
+==============
+
+When opening a new issue or commenting on existing issues, please
+make sure discussions are related to concrete technical issues
+with geckodriver or Marionette. Questions or discussions are more
+appropriate for the [mailing list].
+
+For issue reports to be actionable, it must be clear exactly
+what the observed and expected behaviours are, and how to set up
+the state required to observe the erroneous behaviour. The most
+useful thing to provide is a minimal HTML document which permits
+the problem to be reproduced along with a [trace-level log] from
+geckodriver showing the exact wire protocol calls made.
+
+Because of the wide variety and different charateristics of clients
+used with geckodriver, their stacktraces, logs, and code examples are
+typically not very useful as they distract from the actual underlying
+cause. **For this reason, we cannot overstate the importance of
+always providing the [trace-level log] from geckodriver.** Bugs
+relating to a specific client should be filed with that project.
-## Code Contributions
+We welcome you to file issues in the [GitHub issue tracker] once you are
+confident it has not already been reported. The [ISSUE_TEMPLATE.md]
+contains a helpful checklist for things we will want to know about
+the affected system, reproduction steps, and logs.
-If you're looking for easy bugs, have a look at
-[issues labelled E-easy](https://github.com/mozilla/geckodriver/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Aeasy+)
-on Github.
+geckodriver development follows a rolling release model as we don’t
+release patches for older versions. It is therefore useful to use
+the tip-of-tree geckodriver binary, or failing this, the latest
+release when verifying the problem. Similarly, as noted in the
+[README], geckodriver is only compatible with the current release
+channel versions of Firefox, and it consequently does not help
+to report bugs that affect outdated and unsupported Firefoxen.
+Please always try to verify the issue in the latest Firefox Nightly
+before you file your bug.
-This document will guide you through the contribution process.
+[mailing list]: #communication
+[trace-level log]: doc/TraceLogs.md
+[GitHub issue tracker]: https://github.com/mozilla/geckodriver/issues
+[README]: ./README.md
+
-### Step 1: Fork
+Writing code
+============
+
+Because there are many moving parts involved remote controlling
+a web browser, it can be challenging to a new contributor to know
+where to start. Please don’t hesitate to [ask questions]!
-Fork the project [on Github](https://github.com/mozilla/geckodriver)
-and check out your copy locally.
+The canonical source code repository of geckodriver is now
+[mozilla-central]. We continue to use the [GitHub issue tracker] as
+a triage ground before actual, actionable bugs and tasks are filed
+in [Bugzilla]. We also have a curated set of [good first bugs]
+you may consider attempting first.
+
+The purpose of this guide _is not_ to make sure you have a basic
+development environment set up. For that there is plentiful
+documentation, such as the [Developer Guide] to get you rolling.
+Once you do, we can get started working up your first patch!
+Remember to [reach out to us] at any point if you have questions.
-```text
-% git clone git@github.com:username/geckodriver.git
-% cd geckodriver
-% git remote add upstream git://github.com/mozilla/geckodriver.git
-```
+[ask questions]: #communication
+[reach out to us]: #communication
+[mozilla-central]: https://searchfox.org/mozilla-central/source/testing/geckodriver/
+[Bugzilla]: https://bugzilla.mozilla.org/buglist.cgi?cmdtype=runnamed&namedcmd=geckodriver&list_id=13825733
+[good first bugs]: https://www.joshmatthews.net/bugsahoy/?automation=1&rust=1
+[Developer Guide]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide
+
-### Step 2: Branch
+Building geckodriver
+--------------------
-Create a feature branch and start hacking:
+geckodriver is written in [Rust], a systems programming language
+from Mozilla. Crucially, it relies on the [webdriver crate] to
+provide the HTTPD and do most of the heavy lifting of marshalling the
+[WebDriver protocol]. geckodriver translates WebDriver [commands],
+[responses], and [errors] to the [Marionette protocol], and acts
+as a proxy between WebDriver clients and [Marionette].
-```text
-% git checkout -b my-feature-branch
-```
+Whilst geckodriver lives in the same source repository as Firefox
+and is built in the [Firefox CI], is _is not_ built if you build
+Firefox locally. To enable building of geckodriver locally, ensure
+you put this in your [mozconfig]:
+
+ ac_add_options --enable-geckodriver
+
+When you have, you are ready to start off your first build:
+
+ % ./mach build testing/geckodriver
+
+The geckodriver executable will appear in `${objdir}/dist/bin/geckodriver`
+alongside firefox-bin. To run it you can use mach:
-We practice HEAD-based development, which means all changes are applied
-directly on top of master.
+ % ./mach geckodriver -- --version
+ 0:00.27 /home/ato/src/gecko/obj-x86_64-pc-linux-gnu/dist/bin/geckodriver --version --binary /home/ato/src/gecko/obj-x86_64-pc-linux-gnu/dist/bin/firefox
+ geckodriver 0.19.0 (f3e939a81ee1169f9501ad96eb43bbf4bf4a1bde 2017-10-11)
-### Step 3: Commit
+[Rust]: https://www.rust-lang.org/
+[webdriver crate]: ../webdriver/README.md
+[commands]: https://docs.rs/webdriver/newest/webdriver/command/index.html
+[responses]: https://docs.rs/webdriver/newest/webdriver/response/index.html
+[errors]: https://docs.rs/webdriver/newest/webdriver/error/enum.ErrorStatus.html
+[Marionette protocol]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/Protocol
+[Marionette]: ../marionette/README.md
+[Firefox CI]: https://treeherder.mozilla.org/
+[mozconfig]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options
-First make sure git knows your name and email address:
-```text
-% git config --global user.name 'Santa Claus'
-% git config --global user.email 'santa@example.com'
-```
+Running the tests
+-----------------
+
+We verify and test geckodriver in a couple of different ways.
+Since it is an implementation of the WebDriver web standard, we share
+a set of conformance tests with other browser vendors through the
+[Web Platform Tests] (WPT) initiative. This lets us ensure web
+compatibility between _different_ WebDriver implementations for
+different browsers.
-The first line must be meaningful as it's what people see when they
-run `git shortlog` or `git log --oneline`.
+In addition to the WPT tests, geckodriver and libwebdriver has
+unit tests. At the moment there is no way to run Rust unit tests
+through mach, although this is being worked on. For the moment
+you need to kick off a separate build using [cargo]:
-### Step 4: Rebase
+ % cd testing/geckodriver
+ Compiling geckodriver v0.19.0 (file:///home/ato/src/gecko/testing/geckodriver)
+ …
+ test result: ok. 7 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
-Use `git rebase` (not `git merge`) to sync your work from time to time.
+Because the unit tests _are not_ currently run in the [Firefox CI],
+hopefully you will find that they all pass. (-:
+
+To run the more extensive WPT tests you can use mach, but first
+make sure you have a build of Firefox:
+
+ % ./mach build
+ % ./mach wpt testing/web-platform/tests/webdriver
-```text
-% git fetch upstream
-% git rebase upstream/master
-```
+As these are functional integration tests and pop up Firefox windows
+sporadically, a helpful tip is to surpress the window whilst you
+are running them by using Firefox’ [headless mode]:
+
+ % MOZ_HEADLESS=1 ./mach wpt testing/web-platform/tests/webdriver
-### Step 5: Push
+In addition to the `MOZ_HEADLESS` output variable there is also
+`MOZ_HEADLESS_WIDTH` and `MOZ_HEADLESS_HEIGHT` to control the
+dimensions of the no-op virtual display. This is similar to using
+xvfb(1) which you may know from the X windowing system, but has
+the additional benefit of also working on macOS and Windows.
-```text
-% git push my-feature-branch
-```
+As you get in to development of geckodriver and Marionette you will
+increasingly grow to understand our love for [trace-level logs].
+They provide us with the input—the HTTP requests—from the client
+(in WPT’s case from the tests’ use of a custom WebDriver client),
+the translation geckodriver makes to the [Marionette protocol],
+the log output from Marionette, its responses back to geckodriver,
+and finally the output—or the HTTP response—back to the client.
-Go to https://github.com/yourusername/geckodriver and press the _Pull
-Request_ and fill out the form.
+The [trace-level logs] can be surfaced by passing on the `-vv`
+flag to geckodriver through WPT:
+
+ % ./mach wpt --webdriver-arg=-vv testing/web-platform/tests/webdriver
+
+[Web Platform Tests]: http://web-platform-tests.org/
+[cargo]: http://doc.crates.io/guide.html
+[headless mode]: https://developer.mozilla.org/en-US/Firefox/Headless_mode
-Pull requests are usually reviewed within a few days. Reviews will be done
-through [Reviewable](https://reviewable.io/reviews/mozilla/geckodriver)
+
+Submitting patches
+------------------
-### Step 6: Integration
+You can submit patches by uploading .diff files to Bugzilla or by
+sending them to [MozReview].
+
+Once you have contributed a couple of patches, we are happy to
+sponsor you in [becoming a Mozilla committer]. When you have been
+granted commit access level 1 you will have permission to use the
+[Firefox CI] to trigger your own “try runs” to test your changes.
-When code review is complete, a committer will take your PR and
-integrate it on geckodriver's master branch. Because we like to keep a
-linear history on the master branch, we will normally squash and rebase
-your branch history.
+[MozReview]: http://mozilla-version-control-tools.readthedocs.io/en/latest/mozreview.html
+[becoming a Mozilla committer]: https://www.mozilla.org/en-US/about/governance/policies/commit/
+
+
+Communication
+=============
-## Communication
+The mailing list for geckodriver discussion is
+tools-marionette@lists.mozilla.org ([subscribe], [archive]).
-geckodriver contributors frequent the `#ateam` channel on
-[`irc.mozilla.org`](http://chat.mibbit.com/?server=irc.mozilla.org:#ateam).
+If you prefer real-time chat, there is often someone in the #ateam IRC
+channel on irc.mozilla.org. Don’t ask if you can ask a question, just
+ask, and please wait for an answer as we might not be in your timezone.
+
+[subscribe]: https://lists.mozilla.org/listinfo/tools-marionette
+[archive]: http://groups.google.com/group/mozilla.tools.marionette