Bug 2025987 - Document WNP/release notes URL configuration and improve staging release docs

explanations/balrog/index.rst

@@ -12,4 +12,5 @@ Contents:
     update_to_last_good_build.rst
     win32-win64-migration-balrog.rst
     os-de-support.rst
+    wnp-release-notes-urls.rst
 

explanations/balrog/wnp-release-notes-urls.rst

@@ -0,0 +1,45 @@
+WNP and Release Notes URL Configuration
+========================================
+
+The What's New Page (WNP) and release notes URLs that Balrog delivers to Firefox
+clients are configured in ``browser/config/whats_new_page.yml`` in the Firefox
+repository.
+
+``whats_new_page.yml`` entry types
+-----------------------------------
+
+``product-details``
+    Sets the ``detailsURL`` (release notes link, shown in About Firefox and the
+    update prompt) for all channels.
+
+``show-url``
+    Sets the ``openURL`` (What's New Page shown after an update) conditionally
+    per channel, locale list, and version range. Must include
+    ``blob-types: [wnp]`` to ensure the entry only appears in the WNP blob.
+
+URL placeholder resolution
+---------------------------
+
+- ``{product}``, ``{version}``, ``{version.major_number}``: resolved at task
+  generation time by the ``release-balrog-submit-toplevel`` taskgraph transform.
+- ``%LOCALE%``, ``%OLD_VERSION%``: resolved by Balrog at update delivery time.
+
+Client-side release notes links
+---------------------------------
+
+The release notes links in the Firefox UI (About dialog, update prompt) are set
+per-branding in ``browser/branding/*/pref/firefox-branding.js`` via:
+
+- ``app.releaseNotesURL``
+- ``app.releaseNotesURL.aboutDialog``
+- ``app.releaseNotesURL.prompt``
+
+The nightly fallback WNP URL is set via ``startup.homepage_override_url`` in
+the nightly branding pref file.
+
+Windows installer
+------------------
+
+``URLUpdateInfo`` in ``browser/branding/official/branding.nsi`` sets the
+"Update information" URL written to the Windows registry uninstall key. Only
+written for Release and ESR builds (not beta, nightly, or aurora).

how-to/releaseduty/desktop/staging-release.rst

@@ -21,16 +21,29 @@ How-To
 
 -  hop on ``central`` repository
 -  make sure you're up to date with the tip of the repo
--  ``mach try release --version <future-version.0b1> --migration central-to-beta --tasks staging --disable-pgo``
+-  ``mach try release --version "$(cat browser/config/version.txt | sed 's/a/b/')" --migration main-to-beta --tasks staging --disable-pgo``
 
 **For beta to release migration**
 
 -  hop on ``beta`` repository
 -  make sure you're up to date with the tip of the repo
 -  ``mach try release --version <future-version.0> --migration beta-to-release --tasks staging --disable-pgo``
 
+**For a release simulation starting from main (both migrations)**
+
+-  hop on ``main`` repository
+-  ``mach try release --migration main-to-beta --migration beta-to-release --version "$(cat browser/config/version.txt | sed 's/a1//')" --tasks staging --disable-pgo``
+
 .. note:: Get ``future-version`` from `shipit-staging <https://shipit.staging.mozilla-releng.net/>`__. Ie.: If the version in shipit is ``94.0b14`` use ``94.0b15``
 
+The ``--tasks`` flag controls how many tasks are included in the try push:
+
+- ``staging`` (default): only shippable build-phase tasks — the minimal set
+  needed before triggering a staging release via
+  `ShipIt staging <https://shipit.staging.mozilla-releng.net/>`_.
+- ``release-sim``: simulates a full release branch push, including tests —
+  used by sheriffs to check for branch-dependent test failures.
+
 These will create try pushes that look-alike the repos once they are
 merged. Once the decision tasks of the newly created CI graphs are
 green, staging releases can be created off of them via the

how-to/troubleshoot/update-verify-logs.rst

@@ -191,7 +191,7 @@ These tests are a subset of the complete tests. Specifically, they download:
     Got this response:
     <?xml version="1.0"?>
     <updates>
-        <update actions="showURL" appVersion="142.0" buildID="20250207232657" detailsURL="https://www.mozilla.org/en-CA/firefox/142.0/releasenotes/" displayVersion="142.0 Beta 5" openURL="https://www.mozilla.org/en-CA/firefox/142.0beta/whatsnew/?oldversion=%OLD_VERSION%&amp;utm_medium=firefox-desktop&amp;utm_source=update&amp;utm_campaign=142.0beta" type="minor">
+        <update actions="showURL" appVersion="142.0" buildID="20250207232657" detailsURL="https://www.firefox.com/en-CA/firefox/142.0/releasenotes/" displayVersion="142.0 Beta 5" openURL="https://www.firefox.com/en-CA/whatsnew/142.0beta/?oldversion=%OLD_VERSION%&amp;utm_medium=firefox-desktop&amp;utm_source=update&amp;utm_campaign=142.0beta" type="minor">
             <patch type="complete" URL="https://ftp.stage.mozaws.net/pub/firefox/candidates/142.0b5-candidates/build1/update/linux-x86_64/en-CA/firefox-142.0b5.complete.mar" hashFunction="sha512" hashValue="657e9e6b802bd879428dd608924198018f690db28afedbf42b964835571ae4dcd692559f93c4da82ac532b74e97bf9d25fb4041c1e8df63717c1e26fd28c37b9" size="69608506"/>
         </update>
     </updates>