Bug 1365216 - DevTools: bring over documentation for how to find documentation into the tree. r=pbro

MozReview-Commit-ID: 1dTTTVBB59k

--HG--
extra : rebase_source : 9e4af46b13ff7ef93f318abbb8e9f54b539a037a

devtools/docs/README.md

@@ -1,13 +1,20 @@
 # Firefox Developer Tools
 
-Hello! This documentation is for developers who want to work on the developer tools.
+**Hello!**
 
-If you are looking for general docs about how to use the tools, checkout [this MDN page](https://developer.mozilla.org/en-US/docs/Tools) instead.
+This documentation is for developers who want to work on the developer tools. [Get started here](./getting-started/).
 
-If you are looking for a getting started guide on the developer tools, all of this information is documented on the [Hacking](https://wiki.mozilla.org/DevTools/Hacking) wiki page.
+If you are looking for end user documentation, check out [this MDN page](https://developer.mozilla.org/en-US/docs/Tools) instead.
 
-[GitBook](https://github.com/GitbookIO/gitbook) is used to generate online documentation from the markdown files here.
-Here is how you can re-generate the book:
+Happy developing!
+
+## About this documentation
+
+This guide is built with MarkDown files and [GitBook](https://github.com/GitbookIO/gitbook).
+
+The source code for this documentation is distributed with the source code for the tools, in the `docs/` folder.
+
+If you want to contribute to the documentation, [clone the repository](./getting-started/build.md#getting-the-code), make your changes locally, and then regenerate the book to see how it looks like before submitting a patch:
 
 ```bash
 # Install GitBook locally
@@ -19,6 +26,8 @@ cd /path/to/mozilla-central/devtools/docs/
 # Generate the docs and start a local server
 gitbook serve
 
-# Or just built the book
+# You can now navigate to localhost:4000 to see the output
+
+# Or build the book only (this places the output into `docs/_book`)
 gitbook build
-```
+```

devtools/docs/SUMMARY.md

@@ -1,6 +1,14 @@
 
 # Summary
 
+* [Getting started](getting-started/README.md)
+  * [Where is the code?](getting-started/where-is-the-code.md)
+  * [Servers and actors](getting-started/servers-and-actors.md)
+  * [Set up to build DevTools](getting-started/build.md)
+  * [Development profiles](getting-started/development-profiles.md)
+* [Bugs and issue trackers](bugs-issues.md)
+* [Files and directories](files/README.md)
+  * [Adding New Files](files/adding-files.md)
 * [Tool Architectures](tools/tools.md)
   * [Inspector](tools/inspector.md)
     * [Panel Architecture](tools/inspector-panel.md)
@@ -29,8 +37,6 @@
     * [Writing Actors With protocol.js](backend/protocol.js.md)
     * [Registering A New Actor](backend/actor-registration.md)
     * [Actor Best Practices](backend/actor-best-practices.md)
-* [Files and directories](files/README.md)
-  * [Adding New Files](files/adding-files.md)
 * [Automated tests](tests/README.md)
   * Running tests
     * [`xpcshell`](tests/xpcshell.md)

devtools/docs/bugs-issues.md

@@ -0,0 +1,6 @@
+# Bugs and issue trackers
+
+Since we have code in two different places, issues and bugs are to be found in two different places:
+
+* For code in `m-c`: [http://firefox-dev.tools/](http://firefox-dev.tools/) which also lets you filter by good bugs for beginners.
+* For code in `devtools-html`: [this page](https://github.com/search?l=&q=org%3Adevtools-html+state%3Aopen&type=Issues) lists all the issues across the organisation and these are [available issues](https://github.com/search?l=&q=org%3Adevtools-html+state%3Aopen+label%3Aavailable&type=Issues) i.e. ready to be worked on.

devtools/docs/files/README.md

@@ -6,7 +6,7 @@ This page provides a very top level overview of what is on each directory in the
   * `devtools/shared/client`: Code for the [Remote Debugging Protocol](../backend/protocol.md) (RDP) client. You may wonder why this is not in `devtools/client` below: it's mainly because tests in server also need access to the RDP client.
   * `devtools/shared/locales`: Strings used in either the server only, or shared with both the client and server.
 * `devtools/server`: Code for the [RDP](../backend/protocol.md) server and transport layer.
-  * `devtools/server/actors`: [RDP Actors](../backend/protocol.md#actors). Note that if you're modifying actors, you may need to worry about [backwards compatibility](../backend/backwards-compatibility.md) with older clients.
+  * `devtools/server/actors`: [RDP Actors](../backend/protocol.md#actors). Note that if you're modifying actors, you may need to worry about [backwards compatibility](../backend/backward-compatibility.md) with older clients.
 * `devtools/client`: Code for the front-end side of our tools. In theory, each directory corresponds to a panel, but this is not always the case. This directory is only shipped with desktop Firefox, as opposed to other directories above, which are shipped with all Gecko products (Firefox for Android, etc.)
   * `devtools/client/locales`: Strings used in the client front-end.
   * `devtools/client/themes`: CSS and images used in the client front-end.

devtools/docs/getting-started/README.md

@@ -0,0 +1,12 @@
+# Getting started
+
+1. Learn [where the code is](./getting-started/where-is-the-code.md) and about the [architecture](./getting-started/servers-and-actors.md) of the tools.
+2. [Set up your machine](./getting-started/build.md) to build the tools, then [configure a development profile](getting-started/development-profiles.md).
+3. You can now experiment by changing things and rebuilding, look at the [files and directories overview](../files/README.md) or you could also [find something to work on](./bugs-issues.md).
+
+## Additional documentation
+
+* [Mozilla Developer Network](http://developer.mozilla.org/) (also known as *MDN*) has a lot of information about XUL elements, HTML, JS, DOM, Web APIs, Gecko-specific APIs, and more.
+* [DXR](http://dxr.mozilla.org/mozilla-central/source/) is a source code search engine - search for symbols you want to learn about, eg. `nsIDocument`. [Searchfox](http://searchfox.org/mozilla-central/source) is an alternative.
+
+It is a good idea to [add smart keyword searches](https://support.mozilla.org/en-US/kb/how-search-from-address-bar) for DXR and MDN, so you can search faster.

devtools/docs/getting-started/build.md

@@ -0,0 +1,117 @@
+# Set up to build Firefox Developer Tools
+
+These are the steps we're going to look at:
+
+* [Getting the code](#getting-the-code)
+  * [using Mercurial](#using-mercurial-hg)
+  * [using Git](#using-git)
+* [Building and running locally](#building-and-running-locally)
+  * [Rebuilding](#rebuilding)
+  * [Artifact builds](#building-even-faster-with-artifact-builds) for even faster builds
+  * [Maybe you don't even need to build](#maybe-you-dont-even-need-to-build)
+
+## Getting the code
+
+The code is officially hosted on [a Mercurial repository](https://hg.mozilla.org/mozilla-central/). Despair not! There are ways of accessing this via git. We will explain this too.
+
+Either way takes a long time, because the repository is **B I G**. So be prepared to be patient.
+
+### Using Mercurial (hg)
+
+```bash
+hg clone http://hg.mozilla.org/mozilla-central
+```
+
+### Using git
+
+There is a tool called [git-cinnabar](https://github.com/glandium/git-cinnabar/) that lets you use git on top of a Mercurial repository. There's a bit of setup involved, so we've written [a script to automate](https://github.com/sole/cinnabarify) installing `git-cinnabar` and obtaining the code.
+
+## Building and running locally
+
+Whatever method you used to obtain the code, the build step is the same. Fortunately, the Firefox team has made a very good job of automating this with bootstrap scripts and putting [documentation](https://developer.mozilla.org/En/Simple_Firefox_build) together.
+
+Run:
+
+```bash
+./mach build
+```
+
+If your system needs additional dependencies installed (for example, Python, or a compiler, etc), various diagnostic messages will be printed to your screen. Follow their advice and try building again.
+
+Building also takes a long time (specially on slow computers).
+
+**Note:** if using Windows, you might need to type `mach build` instead (without the `./`).
+
+### Running your own compiled version of Firefox
+
+To run the Firefox you just compiled:
+
+```bash
+./mach run
+```
+
+This will run using an empty temporary profile which is discarded when you close the browser. We will look more into persistent development profiles later.<!--TODO: add link to that section when it's written-->
+
+### Rebuilding
+
+Suppose you pulled the latest changes from the remote repository (or made your own changes) and want to build again.
+
+You can ask the `mach` script to build only changed files:
+
+```bash
+./mach build faster
+```
+
+This should be faster (a matter of seconds).
+
+Sometimes, if you haven't updated in a while, you'll be told that you need to *clobber*, or basically delete precompiled stuff and start from scratch, because there are too many changes. The way to do it is:
+
+```bash
+./mach clobber
+./mach build
+```
+
+### Building even faster with artifact builds
+
+If you are *not* going to modify any C/C++ code (which is rare when working on DevTools), you can use artifact builds. This method downloads prebuilt binary components, and then the build process becomes faster.
+
+Create a file on the root of the repository, called `mozconfig`, with the following content:
+
+```
+# Automatically download and use compiled C++ components:
+ac_add_options --enable-artifact-builds
+ 
+# Write build artifacts to:
+mk_add_options MOZ_OBJDIR=./objdir-frontend
+```
+
+And then you can follow the normal build process again (only *faster*!)
+
+On MacOS you might want to use `MOZ_OBJDIR=./objdir-frontend.noindex` instead. Using the `.noindex` file extension prevents the Spotlight from indexing your `objdir`, which is slow.
+
+For more information on aspects such as technical limitations of artifact builds, read the [Artifact Builds](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Artifact_builds) page.
+
+## Maybe you don't even need to build
+
+Working in DevTools generally involves editing JavaScript files only. This means that often you don't even need to run `./mach build`.
+
+Instead, what you need to do is to save the files you modified, quit Firefox, and reopen it again to use the recently saved files.
+
+With pseudocode:
+
+```
+# 1. Build
+./mach build
+# 2. Run
+./mach run
+# 3. you try out things in the browser that opens
+# 4. fully close the browser, e.g. ⌘Q in MacOS
+# 5. edit JS files on the `devtools` folder, save
+# 6. Back to step 2!
+./mach run
+```
+
+While not as fast as the average "save file and reload the website" *web development workflow*, or newer workflows such as React's reloading, this can still be quite fast. 
+
+And certainly faster than building each time, even with artifact builds.
+

devtools/docs/getting-started/development-profiles.md

@@ -0,0 +1,78 @@
+# Setting up a development profile
+
+You can have various [Firefox profiles](https://developer.mozilla.org/en-US/Firefox/Multiple_profiles) (think of something like "user accounts"), each one with different settings, addons, appearance, etc.
+
+This page will guide you through configuring a new profile to enable development features such as additional logging, dumping of network packets, remote debugging, etc. which will help when working in DevTools.
+
+Many of these changes are achieved by modifying preferences in `about:config`, an special page you can access by entering that in Firefox's URL bar. The first time, it will show you a warning page. Click through and then you can start searching for preferences to modify.
+
+Here's [a support article](https://support.mozilla.org/t5/Manage-preferences-and-add-ons/Configuration-Editor-for-Firefox/ta-p/35030) if you need help.
+
+## Create a permanent profile
+
+We were using a temporary profile in the previous step, [building DevTools](./build.md). The contents of this profile are deleted each time the browser is closed, which means any preferences we set will not persist.
+
+The solution is to create a new profile:
+
+```
+./mach -P development
+```
+
+If this profile doesn't exist yet (quite likely), a window will open offering you options to create a new profile, and asking you which name you want to use. Create a new one, and name it `development`. Then start Firefox by clicking on `Start Nightly`.
+
+Next time you start Firefox with `./mach -P development`, the new profile will be automatically used, and settings will persist between browser launches.
+
+## Enable additional logging
+
+You can change the value of these preferences by going to `about:config`:
+
+| Preference name | Value | Comments |
+| --------------- | --------------- | -------- |
+| `browser.dom.window.dump.enabled` | `true` | Adds global `dump` function to log strings to `stdout` |
+| `devtools.debugger.log` (*) | `true` | Dump packets sent over remote debugging protocol to `stdout`.<br /><br />The [remote protocol inspector add-on](https://github.com/firebug/rdp-inspector/wiki) might be useful too. |
+| `devtools.dump.emit` (*) | `true` | Log event notifications from the EventEmitter class<br />(found at `devtools/shared/event-emitter.js`). |
+
+Preferences marked with a (`*`) also require `browser.dom.window.dump.enabled` in order to work. You might not want to enable *all* of those all the time, as they can cause the output to be way too verbose, but they might be useful if you're working on a server actor, for example<!--TODO link to actors doc-->.
+
+Restart the browser to apply configuration changes.
+
+## Enable remote debugging and the Browser Toolbox
+
+These settings allow you to use the [browser toolbox](https://developer.mozilla.org/docs/Tools/Browser_Toolbox) to inspect the DevTools themselves, set breakpoints inside of DevTools code, and run the [Scratchpad](https://developer.mozilla.org/en-US/docs/Tools/Scratchpad) in the *Browser* environment.
+
+Open DevTools, and click the "Toolbox Options" gear icon in the top right (the image underneath is outdated). <!--TODO update image--> 
+
+Make sure the following two options are checked:
+
+- Enable browser chrome and add-on debugging toolboxes
+- Enable remote debugging
+
+![Settings for developer tools - "Enable Chrome Debugging" and "Enable Remote Debugging"](../resources/DevToolsDeveloperSettings.png)
+
+In `about:config`, set `devtools.debugger.prompt-connection` to `false`.
+
+This will get rid of the prompt displayed every time you open the browser toolbox.
+
+## Enable DevTools assertions
+
+When assertions are enabled, assertion failures are fatal, log console warnings, and throw errors.
+
+When assertions are not enabled, the `assert` function is a no-op.
+
+It also enables the "debug" builds of certain third party libraries, such as React.
+
+To enable assertions, add this to your `.mozconfig`:
+
+```
+ac_add_options --enable-debug-js-modules
+```
+
+And assert your own invariants like this:
+
+```
+const { assert } = require("devtools/shared/DevToolsUtils");
+// ...
+assert(1 + 1 === 2, "I really hope this is true...");
+```
+
+

devtools/docs/getting-started/servers-and-actors.md

@@ -0,0 +1,13 @@
+# Servers and actors
+
+Broadly speaking, the tools are divided in two parts: the server and the client. A **server** is anything that can be debugged: for example, your browser, but it could also be Firefox for Android, running on another device. The **client** is the front-end side of the tools, and it is what developers interact with when using the tools.
+
+Since these two parts are decoupled, we can connect to any server using the same client. This enables us to debug multiple types of servers, using the same protocol to communicate.
+
+You will often hear about `actors`. Each feature that can be debugged (for example, network) is exposed via an `actor`, which provides data about that specific feature. It's up to each server to implement some or all actors; the client needs to find out and decide what it can render on the front-side when it connects to the server. So when we want to debug a new feature, we might need to do work in two parts of the code: the server (perhaps implementing a new actor, or extending existing ones) and the client (to display the debugging data returned by the actor).
+
+Often, an actor will correspond to a panel. But a panel might want to get data from multiple actors.
+
+You might also hear about `the toolbox`. The toolbox is what everyone else calls `developer tools` i.e. the front-end that you see when you open the tools in your browser.
+
+

devtools/docs/getting-started/where-is-the-code.md

@@ -0,0 +1,14 @@
+# Where is the code? (or: `mozilla-central` vs `devtools-html`)
+
+Most of the code is hosted in the Firefox repository (we call it `mozilla-central`, often abbreviated as `m-c`), in the [devtools](https://dxr.mozilla.org/mozilla-central/source/devtools) folder. Development of newer pieces of the tools is happening in GitHub, on the [devtools-html](https://github.com/devtools-html/) organisation.
+
+<!--TODO: table listing components and locations (m-c vs github)-->
+
+Code in `m-c` takes longer to obtain and build, as it involves checking out Firefox's repository and installing tools such as a compiler to build a version of Firefox in your machine.
+
+On the other hand, the repositories in `devtools-html` are more straightforward if you're used to *the GitHub workflow*: you clone them, and then run `npm install && npm run` or similar. Roughly, you can work with each repository individually, and we periodically generate JavaScript bundles that are then copied into `m-c`.
+
+Even if you only want to work on a tool whose code is on `devtools-html`, you might still need to go through the step of getting and compiling the code from `mozilla-central` in order to do integration work (such as updating a tool bundle).
+
+From now on, this guide will focus on building the full DevTools within Firefox. Please refer to individual project instructions for tools hosted in `devtools-html`.
+