Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

6 files changed, 167 insertions, 0 deletions

diff --git a/devtools/docs/contributor/getting-started/README.md b/devtools/docs/contributor/getting-started/README.md
new file mode 100644
index 0000000000..fe21ecbe8d
--- /dev/null
+++ b/devtools/docs/contributor/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/contributor/getting-started/architecture-overview.md b/devtools/docs/contributor/getting-started/architecture-overview.md
new file mode 100644
index 0000000000..c7631fdca3
--- /dev/null
+++ b/devtools/docs/contributor/getting-started/architecture-overview.md
@@ -0,0 +1,11 @@
+# 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/contributor/getting-started/bugzilla.md b/devtools/docs/contributor/getting-started/bugzilla.md
new file mode 100644
index 0000000000..fe68491477
--- /dev/null
+++ b/devtools/docs/contributor/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/contributor/getting-started/development-profiles.md b/devtools/docs/contributor/getting-started/development-profiles.md
new file mode 100644
index 0000000000..99dd370733
--- /dev/null
+++ b/devtools/docs/contributor/getting-started/development-profiles.md
@@ -0,0 +1,105 @@
+# 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))
+
+## Default profile
+
+The following command line expression will run Firefox using a default profile. It'll create the default profile if there isn't one already.
+
+
+```
+./mach run
+```
+
+## Using temporary profile
+
+The following command line expression will run Firefox using a temporary profile which is discarded when you close the browser. It also means that any preferences we set will not persist.
+
+```
+./mach run --temp-profile
+```
+
+## Create a permanent profile
+
+Create a permanent profile can be done as follows:
+
+```
+./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.md)! 😃
+
+---
+
+## 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://firefox-source-docs.mozilla.org/devtools-user/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/contributor/getting-started/restart.png b/devtools/docs/contributor/getting-started/restart.png
new file mode 100644
index 0000000000..a4611e116a
--- /dev/null
+++ b/devtools/docs/contributor/getting-started/restart.png
diff --git a/devtools/docs/contributor/getting-started/where-is-the-code.md b/devtools/docs/contributor/getting-started/where-is-the-code.md
new file mode 100644
index 0000000000..3412bff6a4
--- /dev/null
+++ b/devtools/docs/contributor/getting-started/where-is-the-code.md
@@ -0,0 +1,13 @@
+# 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`.