From dda315bf6a6acee99ce54c2f28ee697d0da54d49 Mon Sep 17 00:00:00 2001
From: Julian Descottes <jdescottes@mozilla.com>
Date: Wed, 7 Dec 2022 09:07:32 +0000
Subject: [PATCH] Bug 1804219 - [remote] Clarify where to add remote
 preferences r=webdriver-reviewers,whimboo,Sasha

Depends on D163891

Differential Revision: https://phabricator.services.mozilla.com/D163922
---
 remote/shared/RecommendedPreferences.sys.mjs  | 44 ++++++++++++++++---
 testing/geckodriver/src/prefs.rs              |  7 +--
 .../client/marionette_driver/geckoinstance.py |  3 ++
 3 files changed, 44 insertions(+), 10 deletions(-)

diff --git a/remote/shared/RecommendedPreferences.sys.mjs b/remote/shared/RecommendedPreferences.sys.mjs
index 2fc2ab9f7a81..12bab002f5d2 100644
--- a/remote/shared/RecommendedPreferences.sys.mjs
+++ b/remote/shared/RecommendedPreferences.sys.mjs
@@ -33,14 +33,48 @@ if (Services.appinfo.processType != Ci.nsIXULRuntime.PROCESS_TYPE_DEFAULT) {
 // Preferences are set for automation on startup, unless
 // remote.prefs.recommended has been set to false.
 //
-// All prefs listed here have immediate effect, and don't require a restart
-// nor have to be set in the profile before the application starts. If such a
-// latter preference has to be added, it needs to be done for the client like
-// Marionette client (geckoinstance.py), or geckodriver (prefs.rs).
-//
 // Note: Clients do not always use the latest version of the application. As
 // such backward compatibility has to be ensured at least for the last three
 // releases.
+
+// INSTRUCTIONS TO ADD A NEW PREFERENCE
+//
+// Preferences for remote control and automation can be set from several entry
+// points:
+// - remote/shared/RecommendedPreferences.sys.mjs
+// - remote/test/puppeteer/src/node/FirefoxLauncher.ts
+// - testing/geckodriver/src/prefs.rs
+// - testing/marionette/client/marionette_driver/geckoinstance.py
+//
+// The preferences in `FirefoxLauncher.ts`, `prefs.rs` and `geckoinstance.py`
+// will be applied before the Application starts, and should typically be used
+// for preferences which cannot be updated during the lifetime of the Application.
+//
+// The preferences in `RecommendedPreferences.sys.mjs` are applied after
+// the Application has started, which means that the application must apply this
+// change dynamically and behave correctly. Note that you can also define
+// protocol specific preferences (CDP, WebDriver, ...) which are merged with the
+// COMMON_PREFERENCES from `RecommendedPreferences.sys.mjs`.
+//
+// Additionally, users relying on the Marionette Python client (ie. using
+// geckoinstance.py) set `remote.prefs.recommended = false`. This means that
+// preferences from `RecommendedPreferences.sys.mjs` are not applied and have to
+// be added to the list of preferences in that Python file. Note that there are
+// several lists of preferences, either common or specific to a given application
+// (Firefox Desktop, Fennec, Thunderbird).
+//
+// Depending on how users interact with the Remote Agent, they will use different
+// combinations of preferences. So it's important to update the preferences files
+// so that all users have the proper preferences.
+//
+// When adding a new preference, follow this guide to decide where to add it:
+// - Add the preference to `geckoinstance.py`
+// - If the preference has to be set before startup:
+//   - Add the preference to `prefs.rs`
+//   - Add the preference `FirefoxLauncher.ts`
+//   - Create a PR to upstream the change on `FirefoxLauncher.ts` to puppeteer
+// - Otherwise, if the preference can be set after startup:
+//   - Add the preference to `RecommendedPreferences.sys.mjs`
 const COMMON_PREFERENCES = new Map([
   // Make sure Shield doesn't hit the network.
   ["app.normandy.api_url", ""],
diff --git a/testing/geckodriver/src/prefs.rs b/testing/geckodriver/src/prefs.rs
index eb582a4ee0a3..d3c874cec10e 100644
--- a/testing/geckodriver/src/prefs.rs
+++ b/testing/geckodriver/src/prefs.rs
@@ -6,11 +6,8 @@ use mozprofile::preferences::Pref;
 
 // ALL CHANGES TO THIS FILE MUST HAVE REVIEW FROM A GECKODRIVER PEER!
 //
-// All preferences in this file are not immediately effective, and
-// require a restart of Firefox, or have to be set in the profile before
-// Firefox gets started the first time. If a preference has to be added,
-// which is immediately effective, it needs to be done in Marionette
-// (RecommendedPreferences.sys.mjs).
+// Please refer to INSTRUCTIONS TO ADD A NEW PREFERENCE in
+// remote/shared/RecommendedPreferences.sys.mjs
 //
 // Note: geckodriver is used out-of-tree with various builds of Firefox.
 // Removing a preference from this file will cause regressions,
diff --git a/testing/marionette/client/marionette_driver/geckoinstance.py b/testing/marionette/client/marionette_driver/geckoinstance.py
index 9530baf705ed..a30fed8ce727 100644
--- a/testing/marionette/client/marionette_driver/geckoinstance.py
+++ b/testing/marionette/client/marionette_driver/geckoinstance.py
@@ -4,6 +4,9 @@
 
 # ALL CHANGES TO THIS FILE MUST HAVE REVIEW FROM A MARIONETTE PEER!
 #
+# Please refer to INSTRUCTIONS TO ADD A NEW PREFERENCE in
+# remote/shared/RecommendedPreferences.sys.mjs
+#
 # The Marionette Python client is used out-of-tree with various builds of
 # Firefox. Removing a preference from this file will cause regressions,
 # so please be careful and get review from a Testing :: Marionette peer