1 files changed, 104 insertions, 0 deletions
diff --git a/dom/quota/scripts/qm-try-analysis/README.md b/dom/quota/scripts/qm-try-analysis/README.md
new file mode 100644
index 0000000000..cef1a6717c
--- /dev/null
+++ b/dom/quota/scripts/qm-try-analysis/README.md
@@ -0,0 +1,104 @@
+# QM_TRY Analysis Guide
+
+Welcome to the QM_TRY Analysis Guide!
+This document walks you through the process of setting up the environment for semi-automatic monitoring of QM_TRY failures within Mozilla.
+Follow these step-by-step instructions to ensure you have the necessary requirements before initiating the analysis.
+
+## Setup Instructions
+
+### 1. Clone mozilla-central
+
+Ensure you have a local clone of mozilla-central.
+If you don't have it yet, refer to [this link](https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html#bootstrap-a-copy-of-the-firefox-source-code).
+Building the project is not necessary for this setup.
+
+### 2. Install rust-code-analysis
+
+If not done already, set up Rust by visiting [rustup.rs](https://rustup.rs/).
+Once Rust is installed, install rust-code-analysis using the following command:
+
+```bash
+cargo install --git https://github.com/mozilla/rust-code-analysis --rev 56f182ac570
+```
+
+### 3. Obtain Telemetry API Key
+
+Obtain a Telemetry API Key by visiting [Telemetry API Key](https://sql.telemetry.mozilla.org/users/me).
+Save this key for later use in the analysis scripts.
+
+### 4. Obtain Bugzilla API Key
+
+Obtain your Bugzilla API Key from [Bugzilla User Preferences](https://bugzilla.mozilla.org/userprefs.cgi?tab=apikey).
+
+### 5. Install Python
+
+Install Python if not already set up.
+
+### 6. Install Poetry and set up dependencies
+
+If you haven't installed Poetry, use the following commands to install it and set up the project:
+
+```bash
+pip install poetry
+cd mozilla-unified/dom/quota/scripts/qm-try-analysis
+poetry install
+```
+
+### Containerized setup
+
+To streamline the setup process, use [`Podman`](https://github.com/containers/podman?tab=readme-ov-file#podman-a-tool-for-managing-oci-containers-and-pods) with the provided `Containerfile`. Navigate to the relevant directory:
+
+```bash
+cd mozilla-unified/dom/quota/scripts/qm-try-analysis
+```
+
+Build the container image and run the container:
+
+```bash
+podman run -it $(podman build -q .) -v <path on your system>:/home/scripts/qm-try-analysis/output
+```
+
+## Effort
+
+- Each run takes approximately 5–15 minutes, with scripts running in less than 5 minutes.
+- Analysis is performed once a week (as of November 2023) on Monday.
+
+## Generate Output
+
+Navigate to the analysis directory:
+
+```bash
+cd mozilla-unified/dom/quota/scripts/qm-try-analysis
+```
+
+The process involves fetching data, analyzing, and reporting. Here's a quick overview:
+
+```bash
+# Jump into a poetry shell session
+poetry shell
+
+# Fetch data
+qm-try-analysis fetch [OPTIONS]
+
+# Analyze data
+qm-try-analysis analyze [OPTIONS]
+
+# Report failures to Bugzilla
+qm-try-analysis report [OPTIONS]
+
+# To exit the shell session
+exit
+```
+
+Refer to the detailed usage instructions provided by adding the `--help` option to one of the commands above.
+
+## Analysis
+
+- Look for noticeable problems such as new errors, unusual stacks, or issues not encountered for a long time.
+
+## Additional Hints
+
+- Treat QM_TRY bugs as meta bugs; do not attach patches there; create a new bug for that and cross-link using blocks/depends on.
+- Interesting bugs to cross-link:
+  - [Bug 1705304](https://bugzilla.mozilla.org/show_bug.cgi?id=1705304) (FATAL errors): "error conditions we cannot meaningfully recover from."
+  - [Bug 1712582](https://bugzilla.mozilla.org/show_bug.cgi?id=1712582) (Replace generic NS_ERROR_FAILURE errors with more specific codes).