8 files changed, 505 insertions, 0 deletions

diff --git a/devtools/docs/getting-started/README.md b/devtools/docs/getting-started/README.md
new file mode 100644
index 0000000000..9a43b4d7b3
--- /dev/null
+++ b/devtools/docs/getting-started/README.md
@@ -0,0 +1,29 @@
+# Getting started
+
+Hello, and thanks for your interest in contributing to Firefox DevTools!
+
+DevTools is a complex web app, but if you're familiar with either HTML/CSS or JavaScript, you can contribute! The process goes like this:
+
+- Claim a bug
+- Set up your dev environment
+- Write the patch and get it reviewed
+
+Feel free to ask questions at any point on [Matrix](https://chat.mozilla.org/#/room/#devtools:mozilla.org).
+
+## Claim a bug
+
+Visit the [Codetribute](https://codetribute.mozilla.org/projects/devtools) bug tracker and find a bug you like. Anything labeled **good-first-bug** is perfect for a newcomer. Many of these tasks will make a visible impact to the DevTools UI.
+
+Claim the bug by creating a Bugzilla account and posting a comment on the bug’s page to say that you’d like to work on it. Ask questions if you have any uncertainty about what the bug means.
+
+## Set up your dev environment
+
+Follow the steps of Firefox’s [contributor guide](https://firefox-source-docs.mozilla.org/contributing/how_to_contribute_firefox.html) to install and run Firefox locally. During installation, follow the steps for “Artifact Mode.” 
+
+If you run into errors about missing libraries, search the web to learn how to install whatever is missing. If you get stuck, ask for help on [Matrix](https://chat.mozilla.org/#/room/#devtools:mozilla.org).
+
+## Write the patch and get it reviewed
+
+The rest of this documentation has info on coding standards as well as specifics of DevTools architecture.
+
+When you’re ready to commit your changes, you can ask the bug’s mentor to review, or refer to the list of [DevTools team members](https://firefox-dev.tools/#about-devtools).
diff --git a/devtools/docs/getting-started/architecture-overview.md b/devtools/docs/getting-started/architecture-overview.md
new file mode 100644
index 0000000000..9c35a13252
--- /dev/null
+++ b/devtools/docs/getting-started/architecture-overview.md
@@ -0,0 +1,13 @@
+# Architecture overview 
+
+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.
+
+
diff --git a/devtools/docs/getting-started/bugzilla.md b/devtools/docs/getting-started/bugzilla.md
new file mode 100644
index 0000000000..fe68491477
--- /dev/null
+++ b/devtools/docs/getting-started/bugzilla.md
@@ -0,0 +1,9 @@
+# Get a Bugzilla account
+
+Mozilla's bug tracker is at [https://bugzilla.mozilla.org/](https://bugzilla.mozilla.org/), which is often abbreviated as `BMO`.
+
+You don't need an account if you simply want to build the code and modify it, but you will need an account in Bugzilla if you want to file or comment on bugs, send patches, get assigned to bugs (so you can 'claim' them), etc.
+
+**Note**: if you are a Mozilla employee, don’t use an email alias to sign up, use your full LDAP account.
+
+To make yourself easier to find by other colleagues (for example when they're trying to set a reviewer for a patch), you can [edit the *real name* field](https://bugzilla.mozilla.org/userprefs.cgi?tab=account) to add your alias or any other word they might use to search for you there. The convention is to use something like `Your Name :alias :ldap/:ircnick`. For example: `Mary Smith :mary :msmith`
diff --git a/devtools/docs/getting-started/build.md b/devtools/docs/getting-started/build.md
new file mode 100644
index 0000000000..eb93367fca
--- /dev/null
+++ b/devtools/docs/getting-started/build.md
@@ -0,0 +1,159 @@
+# Set up to build Firefox Developer Tools
+
+Since the tools are part of Firefox, we need to get and build Firefox's source code.
+
+These are the steps we're going to look at:
+
+* [Installing Mercurial](#installing-mercurial)
+* [Getting the code](#getting-the-code)
+* [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)
+
+## Installing Mercurial
+
+Firefox's source code is hosted on [a Mercurial repository](https://hg.mozilla.org/mozilla-central/).
+
+Please [install Mercurial](https://www.mercurial-scm.org/) if it's not already installed in your system. Its website provides [files for downloading](https://www.mercurial-scm.org/downloads) and also instructions for the most popular package managers. For example, if using Homebrew in macOS:
+
+```bash
+brew install mercurial
+```
+
+Or in Debian/Ubuntu Linux with apt-get:
+
+```bash
+apt-get install mercurial
+```
+
+## Getting the code
+
+This will take a long time, because the repository is **B  I  G** (Firefox is more than 10 years old and there are lots of commits every day!). So please be patient.
+
+You will also need a lot of disk space (about ~40Gb free).
+
+```bash
+cd ~ # or the folder where you store your projects, for example ~/projects
+hg clone https://hg.mozilla.org/mozilla-central
+```
+
+## Building and running locally
+
+Although DevTools is written in JavaScript, the core of Firefox is not—we need tools such as compilers to build the C/C++/Rust code and turn it into binaries that our computer can run.
+
+If you're a web developer, you might not be familiar with these tools, but fortunately, the Firefox team has made a very good job of automating the process of installing them with bootstrap scripts, and putting [documentation](https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_build) together. You don't *need* to read it now; as we'll provide a simplified way to build the code, but if you have any issues, please refer to the documentation.
+
+Try building Firefox and downloading dependencies by running the following commands:
+
+```bash
+./mach bootstrap
+```
+
+This script might ask you questions, so it's recommended to keep an eye on the terminal while it's running—otherwise it will never finish!
+
+*Please note, when you are prompted for your name and add unicode characters this can crash the process. The workaround here is to use ascii-friendly characters and later on edit your `~/.hgrc` file manually to use the unicode characters in your name.*
+
+After it finishes, you might be asked to add some lines to a `mozconfig` file. Create this file in the repository folder (i.e. in `~/mozilla-central`), then add the lines.
+
+Then run this:
+
+```bash
+./mach configure
+./mach build
+```
+
+Please note, if this fails it might be possible you need to run the `bootstrap.py` script first. Download the [bootstrap.py script](https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py) and save it in your project directory. Then run `python bootstrap.py` and follow the prompted steps.
+
+**Note:** if using Windows, you might need to type the commands without the `./`:
+
+```bash
+mach bootstrap
+mach configure
+mach build
+```
+
+If your system needs additional dependencies installed (for example, Python, or a compiler, etc) the above commands might fail, and various diagnostic messages will be printed to your screen. Follow their advice and then try running the command that failed again, until the three of them complete successfully.
+
+Some error messages can be quite cryptic. It is a good idea to consult the [documentation](https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_build) specific to the platform you're using. Sometimes searching in the internet for the specific error message you get can help, and you can also [get in touch](https://firefox-dev.tools/#getting-in-touch) if you get stuck.
+
+Once you complete a first successful build, you should be able to build again by running only this command:
+
+```bash
+./mach build
+```
+
+By the way, building takes a long time (specially on slow computers).
+
+### 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 into [persistent development profiles later](./development-profiles.md). But first...
+
+⭐️  **Time for some congratulations!** You managed to get Firefox's code, build tools and dependencies, and just run your very own copy of Firefox! Well done! ⭐   ️ 
+
+### Rebuilding
+
+<!--TODO: it would be valuable to explain how to pull changes! -->
+
+Suppose you pulled the latest changes from the remote repository (or made some changes, to experiment and see what happens) 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
+```
+
+It is a bit tedious to do this manually, but fortunately you can add an entry to `mozconfig` to have this done automatically for you each time it's required. Add this and save the file:
+
+```
+# Automatically clobber when an incremental build is not possible
+mk_add_options AUTOCLOBBER=1
+```
+
+### Building even faster with artifact builds
+
+It is unusual to modify C/C++ code when working on DevTools. This means that we can use *artifact builds*. This method downloads prebuilt binary components, and then the build process becomes faster.
+
+Add the following content to `mozconfig`:
+
+```bash
+# 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*!)
+
+**Note**: 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.
+
+### Updating worker code requires a few extra steps
+
+#### Prerequisite
+
+1. Install yarn 1.x globally via `npm install -g yarn` if you do not have it installed globally already.
+2. Go to the `client/debugger/` directory and run `npm install`.
+
+#### Regenerating work bundle
+
+1. Save the modified files.
+2. Back in your terminal, under `client/debugger/` directory, execute `node bin/build`.
+3. After completion, use the `Restart (Developer)` option that is available under the `File` menu in local builds (or its respective shortcut).
+
diff --git a/devtools/docs/getting-started/development-profiles.md b/devtools/docs/getting-started/development-profiles.md
new file mode 100644
index 0000000000..41990eda94
--- /dev/null
+++ b/devtools/docs/getting-started/development-profiles.md
@@ -0,0 +1,90 @@
+# 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`, a special page you can access by typing in `about:config` in Firefox's URL bar. The first time, it will show you a warning page. Click through or disable the warning for the future, and then you can start searching for preferences to modify.
+
+(If you're curious, here's more information about [about:config](https://support.mozilla.org/en-US/kb/about-config-editor-firefox))
+
+## 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 permanent profile:
+
+```
+./mach run -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 for the name you want to use.
+
+Create a new profile, and name it `development`. Then start Firefox by clicking on `Start Nightly`.
+
+Next time you start Firefox with `./mach run -P development`, the new profile will be automatically used, and settings will persist between browser launches.
+
+It's now time to [start contributing](../contributing.html)! 😃
+
+---
+
+## Advanced settings
+
+The following section describes how to enable additional development features; don't worry if you don't understand what some of these are or what they're for. Feel free to skip these if you're new; you probably don't need them yet.
+
+### 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.console.stdout.chrome` | `true` | Allows console API to write to `stdout` when used by chrome content |
+| `devtools.console.stdout.content` | `true` | Allows console API to write to `stdout` when used by content |
+| `devtools.debugger.log` (*) | `true` | Dump packets sent over remote debugging protocol to `stdout`.<!-- TODO: I think this is outdated and there isn't a compatible addon anymore <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
+
+<!--TODO: aren't some of these preferences enabled by default now in local builds? -->
+
+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 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` file:
+
+```
+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...");
+```
diff --git a/devtools/docs/getting-started/restart.png b/devtools/docs/getting-started/restart.png
new file mode 100644
index 0000000000..a4611e116a
--- /dev/null
+++ b/devtools/docs/getting-started/restart.png
diff --git a/devtools/docs/getting-started/setting-up-mozilla-central-for-macOS.md b/devtools/docs/getting-started/setting-up-mozilla-central-for-macOS.md
new file mode 100644
index 0000000000..4159bedea6
--- /dev/null
+++ b/devtools/docs/getting-started/setting-up-mozilla-central-for-macOS.md
@@ -0,0 +1,191 @@
+## Table of contents
+
+To set up `mozilla-central`, follow parts 1-6. Part 7 is for debugging common errors that may pop up during the process.
+
+1) Before you start
+2) Bootstrapping your modules
+3) Cloning mozilla-central
+4) Bootstrapping mozilla-central
+5) Setting up arcanist and moz-phab
+6) Making your first practice patch
+7) Common errors
+
+## Before you start
+
+1) Install [Xcode](https://developer.apple.com/xcode/).
+2) Install [Homebrew](https://brew.sh/).
+
+## Bootstrapping your modules
+
+1) Create a "src" directory for yourself under your home directory:
+```
+mkdir src && cd src
+```
+
+2) Download the [bootstrap.py](https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py) script and save it in your `src/` directory.
+
+3) Run the bootstrap script with:
+```
+python bootstrap.py
+```
+
+4) Follow the prompts, which should be mostly Yes (`Y`). One of the prompts will ask you if you want to clone mozilla-unified. Leave the destination field empty and hit Enter.
+
+## Cloning mozilla-central
+
+In your `src` folder run the following:
+```
+hg clone https://hg.mozilla.org/mozilla-central/ mozilla-central
+```
+
+Your directory should now look something like this:
+```
+src
+  |--- mozilla-central
+  |--- bootstrap.py
+```
+
+Go ahead and open your cloned `mozilla-central` folder:
+```
+cd mozilla-central
+```
+
+## Bootstrapping mozilla-central
+
+1. Run the command below to bootstrap your mozilla-central:
+```
+./mach bootstrap
+```
+
+2. At the end of the bootstrapping process, it will ask you to create a `mozconfig` file. Create a file named `mozconfig` in the `mozilla-central` folder, and paste the following. Afterwards, save that file:
+```
+ac_add_options --enable-artifact-builds
+``` 
+
+3. Run the command below to build mozilla-central
+```
+./mach build
+```
+
+4. If your build is successful, it should tell you that you can now run `./mach run`. Go ahead and do that to run Firefox!
+```
+./mach run
+```
+
+## Setting up arcanist and moz-phab
+
+Follow these instructions here: https://moz-conduit.readthedocs.io/en/latest/arcanist-macos.html.
+
+If at the end of the instructions you try to run `moz-phab -h` and it can't find the command, edit your `.bash_profile`:
+```
+sudo nano ~/.bash_profile
+```
+
+Enter your password, and then paste the string below into that file:
+```
+export PATH="$HOME/.mozbuild/arcanist/bin:$HOME/.mozbuild/moz-phab:$PATH"
+```
+
+Restart your terminal, and `moz-phab -h` should now work as expected.
+
+## Making your first practice patch
+
+To verify that everything works correctly, try submitting a practice patch. These steps are primarily based off of https://moz-conduit.readthedocs.io/en/latest/arcanist-user.html.
+
+Before proceeding, make sure to create a [Phabricator account](https://phabricator.services.mozilla.com). 
+
+1) Go into your mozilla-central folder and setup arc:
+```
+cd mozilla-central
+arc install-certificate
+```
+
+2) Using your editor, create a test file named `testfile`.
+
+3) Check to see if your `testfile` is detected and identified as an untracked file:
+```
+hg status 
+# `? testfile` should be logged in PINK
+```
+
+4) Track your `testfile`:
+```
+hg add testfile
+```
+
+5) Check that the `testfile` is now identified as a tracked file:
+```
+hg status 
+# `A testfile` should be logged in GREEN
+```
+
+6) Commit the tracked changes:
+```
+hg commit -m "Bug N/A - first test patch, please ignore r=davidwalsh"
+```
+
+7) Verify the commit by checking your commit logs:
+```
+hg log
+# Your "Added test file" should appear at the top of the log
+```
+
+8) Submit your patch:
+```
+arc diff
+# this should open a text file with VIM, just fill it similarly to the one below
+```
+
+```
+Bug N/A - first test patch, please ignore r=davidwalsh
+
+Summary: Test patch to see if I set MC correctly. Referring to a benign bug that's CLOSED WONTFIX
+
+Test Plan: N/A
+
+Reviewers: davidwalsh
+
+Subscribers:
+
+Bug #: 1395261
+```
+
+### Finished submitting your patch?
+Double check in Phabricator that it did go through: https://phabricator.services.mozilla.com
+
+## Common Errors
+
+### Checking for rustc... not found
+```
+checking for rustc... not found
+checking for cargo... not found
+```
+
+Install rust and cargo with `curl https://sh.rustup.rs -sSf | sh` and then restart your terminal. Afterwards, install cbindgen with `cargo install cbindgen`.
+
+### Baldrdash
+```
+`Common error: failed to run custom build command for `baldrdash v0.1.0 (directory here)`
+```
+First, delete any existing `gecko-dev` folder that you might have cloned. Afterwards, delete your `mozilla-central` folder and repeat the **Cloning Mozilla Central** steps above.
+
+If you still run into the same error, reinstall llvm with `brew uninstall llvm && brew install llvm`. Again, delete your `mozilla-central` folder and repeat the **Cloning Mozilla Central** steps above.
+
+### Error running mach
+```
+ 0:00.73 /usr/bin/make -f client.mk -s
+ 0:16.13 Error running mach:
+ 0:16.13     ['--log-no-times', 'artifact', 'install']
+```
+Delete your `mozilla-central` folder and repeat the **Cloning Mozilla Central** steps above.
+
+### Packaging specialpowers@mozilla.org.xpi...
+```
+1:28.71 Packaging specialpowers@mozilla.org.xpi...
+ 1:29.14 Traceback (most recent call last):
+ 1:29.14   File "/Users/jarilvalenciano/Desktop/src/mozilla-central/config/nsinstall.py", line 188, in <module>
+ 1:29.14     sys.exit(_nsinstall_internal(argv[1:]))
+ 1:29.14   File "/Users/jarilvalenciano/Desktop/src/mozilla-central/config/nsinstall.py", line 149, in _nsinstall_internal
+ 1:29.14     copy_all_entries(args, target)
+```
+Just run `./mach build` again.
\ No newline at end of file
diff --git a/devtools/docs/getting-started/where-is-the-code.md b/devtools/docs/getting-started/where-is-the-code.md
new file mode 100644
index 0000000000..b89d9cf292
--- /dev/null
+++ b/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://searchfox.org/mozilla-central/source/devtools) folder. Development of some pieces of the tools is happening in GitHub, on the [firefox-devtools](https://github.com/firefox-devtools/) 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`.
+