Bug 1784524: Add basic documentation around Firefox branding & updating macOS icons r=nalexander

Although we do this updates fairly infrequently, these instructions seem like they'll be stable enough that it's worth writing them down.

Differential Revision: https://phabricator.services.mozilla.com/D155581

browser/branding/docs/UpdatingMacIcons.rst

@@ -0,0 +1,26 @@
+.. _updatingmacicons:
+
+====================
+Updating macOS Icons
+====================
+
+macOS icons are stored as ``icns`` files that contain the same logo in multiple different sizes and DPIs. Apple's `Human Interface Guidelines <https://developer.apple.com/design/human-interface-guidelines/foundations/app-icons>`_ should be consulted for the specifics.
+
+These icons can be updated by starting with a PNG of the highest resolution and DPI version, and using these steps to create the others, and the ``icns`` itself:
+
+::
+
+    mkdir firefox.iconset
+    sips -z 16 16     firefox.png --out firefox.iconset/icon_16x16.png
+    sips -z 32 32     firefox.png --out firefox.iconset/icon_16x16@2x.png
+    sips -z 32 32     firefox.png --out firefox.iconset/icon_32x32.png
+    sips -z 64 64     firefox.png --out firefox.iconset/icon_32x32@2x.png
+    sips -z 128 128   firefox.png --out firefox.iconset/icon_128x128.png
+    sips -z 256 256   firefox.png --out firefox.iconset/icon_128x128@2x.png
+    sips -z 256 256   firefox.png --out firefox.iconset/icon_256x256.png
+    sips -z 512 512   firefox.png --out firefox.iconset/icon_256x256@2x.png
+    sips -z 512 512   firefox.png --out firefox.iconset/icon_512x512.png
+    cp firefox.png firefox.iconset/icon_512x512@2x.png
+    iconutil -c icns firefox.iconset
+
+...which will create a ``firefox.icns`` file. You can verify that it includes all of the necessary resolutions and DPIs by inspecting it with ``Preview.app``.

browser/branding/docs/index.rst

@@ -0,0 +1,22 @@
+Firefox Branding
+================
+
+Firefox has multiple different sets of "branding" that are used to hold channel-specific things such as:
+* Logos and other iconography
+* Product names (eg: "Mozilla Firefox", "Firefox Developer Edition")
+* Channel-specific preferences (eg: ``app.update.interval``)
+
+Brandings are stored in the `branding subdirectory <https://searchfox.org/mozilla-central/source/browser/branding>`_ and map to builds as follows:
+
+- ``official`` is used for Release and Beta builds
+- ``aurora`` is used for Developer Edition builds
+- ``nightly`` is used for Nightly and Try builds
+- ``unofficial`` is used when no other branding is specified (eg: local developer builds)
+
+
+Additional reading
+------------------
+
+.. toctree::
+
+   UpdatingMacIcons

browser/branding/moz.build

@@ -0,0 +1,10 @@
+# -*- Mode: python; indent-tabs-mode: nil; tab-width: 40 -*-
+# vim: set filetype=python:
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+SPHINX_TREES["docs"] = "docs"
+
+with Files("docs/**"):
+    SCHEDULES.exclusive = ["docs"]

browser/docs/index.rst

@@ -25,3 +25,4 @@ This is the nascent documentation of the Firefox front-end code.
    base/tabbrowser/index
    touchbar/index
    components/uitour/docs/index
+   branding/docs/index

browser/moz.build

@@ -22,6 +22,7 @@ DIRS += [
     "modules",
     "themes",
     "extensions",
+    "branding",
 ]
 
 DIRS += [