Expand docs on chrome-branded assets

Also adds pointers to the docs from the various resource directories,
following to the original intent with //chrome/app/resources/README.md

Change-Id: I59cca8dcd3f56b53a5d35952cef45a074a085ed5
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4028089
Reviewed-by: David Roger <droger@chromium.org>
Commit-Queue: Colin Blundell <blundell@chromium.org>
Auto-Submit: Nicolas Dossou-Gbété <dgn@chromium.org>
Reviewed-by: Colin Blundell <blundell@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1072752}

chrome/app/resources/README.md

@@ -1 +1,4 @@
-Please read the docs on [Google Chrome branding](../../../docs/google_chrome_branded_builds.md) before checking in resources here.
+If the resource that you want to check in is product-branded and/or trademarked,
+please read the docs on
+[Google Chrome branding](../../../docs/google_chrome_branded_builds.md) to
+determine the correct steps to take.

chrome/app/theme/README.md

@@ -1,12 +1,26 @@
+Branded and Trademarked Assets
+==============================
+
+If the resource that you want to check in is product-branded and/or trademarked,
+please read the docs on
+[Google Chrome branding](../../../docs/google_chrome_branded_builds.md) to
+determine the correct steps to take.
+
 PNG Images
 ==========
 
 Please run src/tools/resources/optimize-png-files.sh on all new icons. For example:
-  tools/resources/optimize-png-files.sh -o2 new_pngs_dir
+
+```sh
+tools/resources/optimize-png-files.sh -o2 new_pngs_dir
+```
 
 If this script does not work for some reason, at least pngcrush the files:
+
+```sh
   mkdir crushed
   pngcrush -d crushed -brute -reduce -rem alla new/*.png
+```
 
 ICO Images
 ==========
@@ -26,20 +40,25 @@ process (using ImageMagick and GIMP) satisfies the above conditions:
 
 1. Convert each of the smaller images to 8-bit. With ImageMagick:
 
+    ```sh
     for f in FILENAME-??.png; \
         do convert $f -dither None -colors 256 \
             png8:`basename $f .png`-indexed.png; \
     done
+    ```
 
 2. Combine the images into an ICO file. With ImageMagick:
 
+    ```sh
     convert FILENAME-256.png FILENAME-{48,32,16}{-indexed,}.png FILENAME.ico
+    ```
 
 3. Unfortunately, the 8-bit images have been converted back into 32-bit images.
    Open the icon in GIMP and re-export it. This will also convert the large
    256 image into a compressed PNG.
-4. Run src/tools/resources/optimize-ico-files.py on the resulting .ico file.
 
-You can also run src/tools/resources/optimize-ico-files.py on existing .ico
+4. Run `src/tools/resources/optimize-ico-files.py` on the resulting .ico file.
+
+You can also run `src/tools/resources/optimize-ico-files.py` on existing .ico
 files. This will convert BMPs to PNGs and run a basic PNG optimization pass, as
 well as fix up any broken image masks (http://crbug.com/534679).

chrome/browser/resources/README.md

@@ -0,0 +1,4 @@
+If the resource that you want to check in is product-branded and/or trademarked,
+please read the docs on
+[Google Chrome branding](../../../docs/google_chrome_branded_builds.md) to
+determine the correct steps to take.

components/resources/README.md

@@ -0,0 +1,4 @@
+If the resource that you want to check in is product-branded and/or trademarked,
+please read the docs on
+[Google Chrome branding](../../docs/google_chrome_branded_builds.md) to
+determine the correct steps to take.

docs/google_chrome_branded_builds.md

@@ -1,22 +1,71 @@
 # Google Chrome branded builds
 
+> Note: to do any of this, an `src-internal` checkout is needed. For more info,
+> see http://go/chrome-linux-build#optional-add-src-internal-to-the-checkout
+
 By default, chromium will build with the open source chromium assets and
-branding (`is_chrome_branded = false` in [GN
- args](https://www.chromium.org/developers/gn-build-configuration), see
-also [Chrome vs. Chromium](chromium_browser_vs_google_chrome.md)).
+branding (`is_chrome_branded = false` in
+[GN args](https://www.chromium.org/developers/gn-build-configuration), see also
+[Chrome vs. Chromium](chromium_browser_vs_google_chrome.md)).
 
 The main reason for this is that the Google Chrome logo and related assets is
 a trademark which we don't want to release under Chromium's open source
 license.
 
-Therefore, if you want to add a trademarked resource, check it into the
-internal repository, and pick a resource based on the branding
-(`is_chrome_branded` in GN, `#if BUILDFLAG(GOOGLE_CHROME_BRANDING)` in cpp). If
-possible, check an open source version into Chromium, so the feature
-continues to work as expected in the open source build.
+Therefore, if you want to add a trademarked resource, check it into an internal
+repository (see section below), and pick a resource based on the branding
+(`is_chrome_branded` in GN, `#if BUILDFLAG(GOOGLE_CHROME_BRANDING)` in cpp, `<if
+expr="_google_chrome">` in grit preprocessing). If possible, check an open
+source version into Chromium, so the feature continues to work as expected in
+the open source build.
 
-E.g. [`//components/resources/default_100_percent/chromium`](../components/resources/default_100_percent/chromium) vs [`//components/resources/default_100_percent/google_chrome`](https://chrome-internal.googlesource.com/chrome/components/default_100_percent/google_chrome/).
+E.g.
+[`//components/resources/default_100_percent/chromium`](../components/resources/default_100_percent/chromium)
+vs
+[`//components/resources/default_100_percent/google_chrome`](https://chrome-internal.googlesource.com/chrome/components/default_100_percent/google_chrome/).
 
-For strings, it’s ok to check them into the open source repository, but make sure that you refer to the correct product, i.e., check in a version of the string that says “Google Chrome” and a version that says “Chromium”.
+For strings, it’s ok to check them into the open source repository, but make
+sure that you refer to the correct product, i.e., check in a version of the
+string that says “Google Chrome” and a version that says “Chromium”.
 
-E.g. [`//chrome/app/chromium_strings.grd`](../chrome/app/chromium_strings.grd) vs [`//chrome/app/google_chrome_strings.grd`](../chrome/app/google_chrome_strings.grd).
+E.g. [`//chrome/app/chromium_strings.grd`](../chrome/app/chromium_strings.grd)
+vs
+[`//chrome/app/google_chrome_strings.grd`](../chrome/app/google_chrome_strings.grd).
+
+## Internal asset repositories
+
+Assets live in various locations based on where they are used: native vs WebUI,
+chrome vs component layer, etc. You can read more about this here:
+[chromium.org | High DPI Resources](https://www.chromium.org/developers/design-documents/high-dpi-resources/)
+
+To check in product-specific assets, in general:
+- Add `//chrome` ones under
+  `//chrome/app/theme[/optional_scale_factor_indicator]/[product_name]`. E.g.
+  [`//chrome/app/theme/default_100_percent/chromium/product_logo_32.png`](../chrome/app/theme/default_100_percent/chromium/product_logo_32.png)
+
+  > Note: WebUI-specific resources should go under
+  > `//chrome/browser/resources/[/optional_scale_factor_indicator]/[product_name]`.
+  > We don't have an internal repo associated yet, so please
+  > [create one](http://go/git-admin-cheatsheet#creating-a-repo) if the use case
+  > comes up.
+
+- Add `//components` ones under
+  `//components/resources[/optional_scale_factor_indicator]/[product_name]`.
+  E.g.
+  [`//components/resources/default_200_percent/chromium/product_logo.png`](../components/resources/default_200_percent/chromium/product_logo.png)
+
+Each `google_chrome` version of a product directory points to a separate
+internal git repo. Some examples:
+- https://chrome-internal.googlesource.com/chrome/theme/google_chrome/
+- https://chrome-internal.googlesource.com/chrome/theme/default_100_percent/google_chrome/
+- https://chrome-internal.googlesource.com/chrome/components/default_200_percent/google_chrome/
+
+To add resources there, `cd` to this repo, add your new assets and `git cl
+upload` to start an internal code review. Once it lands, you will need to create
+a roll CL for the `//../src-internal/DEPS`, using
+[roll-dep](https://chromium.googlesource.com/chromium/tools/depot_tools/+/main/README.md#:~:text=cl.md.-,roll%2Ddep,-%3A%20A%20gclient%20dependency).
+
+Once that CL lands, an auto-roller bot will update the main repo's src-internal
+hash reference in `//DEPS` ([example autoroll CL](https://crrev.com/c/4024955))
+and your new internal resources will be available on the bots. The chromium-side
+CL making use of it can then be uploaded.