Bug 1773203 - [devtools] Improve failure message and documentation for devtools-bundle job r=nchevobbe

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

devtools/client/shared/source-map/README

@@ -7,4 +7,5 @@ The source files for the source-map shared helpers can be found under
 After modifying the sources in debugger/packages/devtools-source-map, regenerate
 the files in this folder by running:
 
-  `yarn && node devtools/client/debugger/bin/bundle.js`
+  > cd devtools/client/debugger
+  > yarn && node bin/bundle.js

devtools/docs/contributor/tests/node-tests.md

@@ -80,3 +80,18 @@ For example, if you need to update snapshots in a specific panel, first locate t
 ## TypeScript
 
 The "performance" suite performs TypeScript checks. The TypeScript usage in the performance panel is documented at [devtools/client/performance-new/typescript.md](https://searchfox.org/mozilla-central/source/devtools/client/performance-new/typescript.md) ([see rendered version on GitHub](https://github.com/mozilla/gecko-dev/blob/master/devtools/client/performance-new/typescript.md)).
+
+## devtools-bundle
+
+The devtools-bundle job is a tier2 job which checks if DevTools bundles are outdated. DevTools bundles are generated JavaScript files built from other dependencies in tree in order to run in specific environments (typically a worker).
+
+All the bundles used by DevTools are generated by devtools/client/debugger/bin/bundle.js. The devtools-bundle job is simply running this script and fails if any versioned file is updated.
+
+In order to fix a failure, you should run the script:
+
+```
+> cd devtools/client/debugger/
+> yarn && node bin/bundle.js
+```
+
+And commit the changes, either in the commit which updated the bundle dependencies, or in a separate commit in order to keep things separated.

taskcluster/scripts/misc/verify-devtools-bundle.py

@@ -28,6 +28,8 @@ status = (
 )
 print(" status:")
 print("-" * 80)
+
+failures = []
 for l in status:
     if not l:
         # Ignore empty lines
@@ -38,11 +40,21 @@ for l in status:
         # building bundles.
         continue
 
-    print(f"TEST-UNEXPECTED-FAIL | devtools-bundle | {l}")
+    failures.append(l)
     overall_failure = True
 
 # Revert all the changes created by `node bin/bundle.js`
 subprocess.check_output(["hg", "revert", "-C", "."])
 
 if overall_failure:
+    doc = "https://firefox-source-docs.mozilla.org/devtools/tests/node-tests.html#devtools-bundle"
+    print(
+        "TEST-UNEXPECTED-FAIL | devtools-bundle | DevTools bundles need to be regenerated, "
+        + f"instructions at: {doc}"
+    )
+
+    print("The following devtools bundles were detected as outdated:")
+    for failure in failures:
+        print(failure)
+
     sys.exit(1)