import of v0.19.1

CHANGES.md

@@ -3,6 +3,27 @@ Change log
 
 All notable changes to this program is documented in this file.
 
+0.19.1 (2017-10-30)
+-------------------
+
+### Changed
+
+- Search suggestions in the location bar turned off as not to
+  trigger network connections
+
+- Block addons incompatible with E10s
+
+### Fixed
+
+- Marionette stacktraces are now correctly propagated
+
+- Some error messages have been clarified
+
+### Removed
+
+- Removed obsolete `socksUsername` and `socksPassword` proxy
+  configuration keys because neither were picked up or recognised
+
 
 0.19.0 (2017-09-16)
 -------------------
@@ -17,11 +38,11 @@ Note that with geckodriver v0.19.0 the following versions are recommended:
   - POST `/session/{session id}/window/minimize` for the [Minimize Window]
     command
 
-- Added preference `extensions.shield-recipe-client.api_url` to disable shield
-  studies which could unexpectedly change the behavior of Firefox
+- Added preference `extensions.shield-recipe-client.api_url` to disable
+  shield studies which could unexpectedly change the behavior of Firefox
 
-- Introduced the temporary, boolean capability `moz:webdriverClick` to enable
-  the WebDriver conforming behavior of the [Element Click] command.
+- Introduced the temporary, boolean capability `moz:webdriverClick` to
+  enable the WebDriver conforming behavior of the [Element Click] command
 
 - Added crashreporter environment variables to better control the browser
   in case of crashes
@@ -57,7 +78,7 @@ Note that with geckodriver v0.19.0 the following versions are recommended:
 - `/moz/addon/install` command accepts an `addon` parameter, in lieu of
   `path`, containing an addon as a Base64 string (fixed by [Jason Juang])
 
-- [webdriver crate] upgraded to version 0.30.0
+- [webdriver crate] upgraded to version 0.31.0
 
 - [mozrunner crate] upgraded to version 0.5.0
 

CONTRIBUTING.md

@@ -1,97 +1,232 @@
-# Contributing to geckodriver
+Contributing
+============
+
+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.
+
+  * [_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.
+
+  * [_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.
+
+[_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.
+
+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.
+
+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.
+
+Once we are satisfied the issue raised is of sufficiently actionable
+character, we will continue with triaging it and file a bug where it
+is appropriate.  Bugs specific to geckodriver will be filed in the
+[`Testing :: geckodriver`] component in Bugzilla.
+
+[mailing list]: #communication
+[trace-level log]: doc/TraceLogs.md
+[GitHub issue tracker]: https://github.com/mozilla/geckodriver/issues
+[README]: ./README.md
+[`Testing :: geckodriver`]: https://bugzilla.mozilla.org/buglist.cgi?component=geckodriver
+
+
+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]!
+
+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 the [`Testing :: geckodriver`] component 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.
+
+[ask questions]: #communication
+[reach out to us]: #communication
+[mozilla-central]: https://searchfox.org/mozilla-central/source/testing/geckodriver/
+[good first bugs]: https://www.joshmatthews.net/bugsahoy/?automation=1&rust=1
+[Developer Guide]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide
+
+
+Building geckodriver
+--------------------
+
+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].
+
+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:
+
+	% ./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)
+
+[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
 
-The geckodriver project welcomes contributions from everyone. There are a
-number of ways you can help:
 
-## Issue Reports
+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.
 
-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.
+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]:
 
-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.
+	% 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
 
-## Code Contributions
+Because the unit tests _are not_ currently run in the [Firefox CI],
+hopefully you will find that they all pass. (-:
 
-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.
+To run the more extensive WPT tests you can use mach, but first
+make sure you have a build of Firefox:
 
-This document will guide you through the contribution process.
+	% ./mach build
+	% ./mach wpt testing/web-platform/tests/webdriver
 
-### Step 1: Fork
+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]:
 
-Fork the project [on Github](https://github.com/mozilla/geckodriver)
-and check out your copy locally.
+	% MOZ_HEADLESS=1 ./mach wpt testing/web-platform/tests/webdriver
 
-```text
-% git clone git@github.com:username/geckodriver.git
-% cd geckodriver
-% git remote add upstream git://github.com/mozilla/geckodriver.git
-```
+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.
 
-### Step 2: 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.
 
-Create a feature branch and start hacking:
+The [trace-level logs] can be surfaced by passing on the `-vv`
+flag to geckodriver through WPT:
 
-```text
-% git checkout -b my-feature-branch
-```
+	% ./mach wpt --webdriver-arg=-vv testing/web-platform/tests/webdriver
 
-We practice HEAD-based development, which means all changes are applied
-directly on top of master.
+[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
 
-### Step 3: Commit
 
-First make sure git knows your name and email address:
+Submitting patches
+------------------
 
-```text
-% git config --global user.name 'Santa Claus'
-% git config --global user.email 'santa@example.com'
-```
+You can submit patches by uploading .diff files to Bugzilla or by
+sending them to [MozReview].
 
-The first line must be meaningful as it's what people see when they
-run `git shortlog` or `git log --oneline`.
+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.
 
-### Step 4: Rebase
+[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/
 
-Use `git rebase` (not `git merge`) to sync your work from time to time.
 
-```text
-% git fetch upstream
-% git rebase upstream/master
-```
+Communication
+=============
 
-### Step 5: Push
+The mailing list for geckodriver discussion is
+tools-marionette@lists.mozilla.org ([subscribe], [archive]).
 
-```text
-% git push my-feature-branch
-```
+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.
 
-Go to https://github.com/yourusername/geckodriver and press the _Pull
-Request_ and fill out the form.
-
-Pull requests are usually reviewed within a few days. Reviews will be done
-through [Reviewable](https://reviewable.io/reviews/mozilla/geckodriver)
-
-### Step 6: Integration
-
-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.
-
-## Communication
-
-geckodriver contributors frequent the `#ateam` channel on
-[`irc.mozilla.org`](http://chat.mibbit.com/?server=irc.mozilla.org:#ateam).
+[subscribe]: https://lists.mozilla.org/listinfo/tools-marionette
+[archive]: http://groups.google.com/group/mozilla.tools.marionette