Add a guide to developing the Hypothesis client

Add an initial guide to developing the Hypothesis client, covering:

 - Installation
 - Getting a local build of the client working with the browser
   extension or a local Hypothesis service
 - Running tests
 - Some basic pointers on code style and where to find guidance for
   creating pull requests

This guide assumes that the service is configured to use the client's
new boot script.

README.md

@@ -23,14 +23,11 @@ be [embedded directly on web pages][embed].
 Development
 -----------
 
-We'll soon be adding instructions on how to set up a development environment for
-the Hypothesis client.
-
-If you are already clear on the difference between this repository and the
-[`hypothesis/h`](https://github.com/hypothesis/h) repository then in the mean
-time the [Contributor's Guide](https://h.readthedocs.io/en/latest/developing/)
-may be of use. Be aware that many instructions in that guide do not apply to
-this repository.
+See the client [Development Guide](/docs/developing.md) for instructions on
+building, testing and contributing to the client.
+
+If you are also interested in developing the Hypothesis service, please see the service's
+[Contributor Guide](https://h.readthedocs.io/en/latest/developing/).
 
 Community
 ---------

docs/developing.md

+# Developing the client
+
+Hypothesis is comprised of several components:
+
+ - A browser-based web app for annotating web pages (this repo)
+ - A service which stores annotations, user accounts and other data. By default
+   the client uses the public service at [hypothes.is](https://hypothes.is).
+ - A browser extension which can add the client to web pages.
+
+In order to develop the client and test out changes you make locally, you will
+need to use either the [browser
+extension](https://github.com/hypothesis/browser-extension) or setup a [a local
+install of the Hypothesis
+service](http://h.readthedocs.io/en/latest/developing/) to host the client.
+
+If you are only interested in making changes to the client, developing using
+the browser extension is the easiest method.
+
+## Prerequisites and Installation
+
+To develop the client, you will need [Node.js v6](https://nodejs.org/en/) or
+later and [gulp](https://github.com/gulpjs/gulp-cli). To install dependencies
+run:
+
+```sh
+npm install -g gulp-cli
+make
+```
+
+## Developing using the browser extension
+
+1. Check out the [browser
+   extension](https://github.com/hypothesis/browser-extension) and follow the
+   steps in the
+   [README](https://github.com/hypothesis/browser-extension/blob/master/README.md)
+   to make it use your local version of the client and the [production
+   Hypothesis
+   service](https://github.com/hypothesis/browser-extension/blob/master/docs/building.md).
+1. Start the client's development server to rebuild the client whenever it
+   changes:
+
+    ```
+    gulp watch
+    ```
+
+1. After making changes to the client, you will need to run `make` in the
+   browser extension repo and reload the extension in Chrome to see changes.
+   You can use [Extensions
+   Reloader](https://chrome.google.com/webstore/detail/extensions-reloader/fimgfedafeadlieiabdeeaodndnlbhid?hl=en)
+   to make this easier.
+
+If you want to use the browser extension together with a local Hypothesis
+service for storing annotations, you should also follow the steps below.
+
+## Developing using a local Hypothesis web service
+
+Once you have a local install of the Hypothesis service set up, you can
+configure it to use a local build of the client. In the client repository, run:
+
+```sh
+export H_SERVICE_URL=http://localhost:5000
+gulp watch
+```
+
+The `H_SERVICE_URL` env var sets the URL of the service which hosts the HTML
+entry point for the client's sidebar application.
+
+In the `hypothesis/h` repository, set the `CLIENT_URL` env var to tell the
+service where to load the client from, before running `make dev`:
+
+```sh
+export CLIENT_URL=http://localhost:3001/hypothesis
+make dev
+```
+
+Once the client and service are running, you can test it out by visiting:
+[http://localhost:3000](http://localhost:3000) or [the Help
+page](http://localhost:5000/docs/help) in your browser.
+
+You can also load the client into your own web pages by adding:
+
+```html
+<script async src="http://localhost:5000/embed.js"></script>
+```
+
+To the page's HTML. Note that this will only work in pages served via plain
+HTTP.  If you want to test out the client on pages served via HTTPS then building
+the client into a browser extension is the easiest option.
+
+## Running tests
+
+Hypothesis uses Karma and mocha for testing. To run all the tests once, run:
+
+```sh
+gulp test
+```
+
+To run tests and automatically re-run them whenever any source files change, run:
+
+```sh
+gulp test-watch
+```
+
+You can filter the tests which are run by passing `--grep <pattern>` as an
+argument to `gulp test`. See the documentation for Mocha's
+[grep](https://mochajs.org/#g---grep-pattern) option.
+
+
+## Code style
+
+### JavaScript
+
+Hypothesis uses ESLint to help maintain style consistency. You can check your
+changes for conformance using:
+
+```
+make lint
+```
+
+Many lint errors can be fixed automatically using:
+
+```
+./node_modules/.bin/eslint --fix
+```
+
+### CSS
+
+Styling is authored in SASS. For guidance on writing CSS for Hypothesis
+projects, please see our [CSS
+Guide](https://github.com/hypothesis/frontend-toolkit/blob/master/docs/css-style-guide.md).
+
+## Submitting pull requests
+
+For general guidance on submitting pull requests to Hypothesis projects, please
+see the [Contributor's Guide](https://h.readthedocs.io/en/latest/developing/).