From 888d525e79e6243bacd02f0ab31dcda66925489c Mon Sep 17 00:00:00 2001 From: Mark Banner Date: Fri, 28 Mar 2025 21:41:22 +0000 Subject: [PATCH] Bug 1956593 - Add region update information to the documentation for Region.sys.mjs. r=daleharvey Differential Revision: https://phabricator.services.mozilla.com/D243173 --- toolkit/modules/Region.sys.mjs | 4 ++-- toolkit/modules/docs/Region.rst | 29 +++++++++++++++++++++++++---- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/toolkit/modules/Region.sys.mjs b/toolkit/modules/Region.sys.mjs index 90afecc22169..640d8f4e9a0f 100644 --- a/toolkit/modules/Region.sys.mjs +++ b/toolkit/modules/Region.sys.mjs @@ -100,8 +100,8 @@ const UPDATE_INTERVAL = 60 * 60 * 24 * 14; const MAX_RETRIES = 3; -// If the user never uses geolocation, schedule a periodic -// update to check the current location (in seconds). +// If the user never uses geolocation, or geolocation is disabled, schedule a +// periodic update to check the current location (in seconds). const UPDATE_CHECK_NAME = "region-update-timer"; const UPDATE_CHECK_INTERVAL = 60 * 60 * 24 * 7; diff --git a/toolkit/modules/docs/Region.rst b/toolkit/modules/docs/Region.rst index 1e95739f4ab7..23ac799467c3 100644 --- a/toolkit/modules/docs/Region.rst +++ b/toolkit/modules/docs/Region.rst @@ -14,20 +14,36 @@ These are tracked separately as to avoid updating the users experience repeatedly as they travel for example. In general callers should use ``Region.home``. -If the user is detected in a current region that is not there `home` region +Region Updating +--------------- + +Firefox `uses a location service`_ that is provided by Mozilla. Firefox will +attempt to check for region on first run of a new profile and +`every 7 days thereafter`_. If an update check fails, then the update will be +retried `after an hour`_ for a `maximum of three times`_. + +If the user is detected in a current region that is not their `home` region for a continuous period (current 2 weeks) then their `home` region will be updated. Testing ======= -To set the users region for testing you can use ``Region._setHomeRegion("US", false)``, the second parameter ``notify`` -will send a notification that the region has changed and trigger a -reload of search engines and other content. +To set the users region for testing you can use: + +.. code-block:: javascript + + let {Region} = ChromeUtils.importESModule("resource://gre/modules/Region.sys.mjs"); + Region._setHomeRegion("US", false) + +Setting the second parameter (``notify``) to true will send an notification that +the region has changed and trigger a reload of search engines and other content. Updating test_Region_geocoding.js data -------------------------------------- +Note: The geocoding feature is not turned on by default. + The test data used in this test is generated by running the MLS geocoding service locally: @@ -70,3 +86,8 @@ Run the script If you want to commit the new test data ~500 seems to be a reasonable number of data points to test before running into issues with the test length. + +.. _every 7 days thereafter: https://searchfox.org/mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf/toolkit/modules/Region.sys.mjs#106 +.. _uses a location service: https://searchfox.org/mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf/modules/libpref/init/all.js#3107 +.. _after an hour: https://searchfox.org/mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf/toolkit/modules/Region.sys.mjs#32-40 +.. _maximum of three times: https://searchfox.org/mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf/toolkit/modules/Region.sys.mjs#101