Bug 1741674 - Advise in each metrics.yaml that we have docs for adding metrics r=TravisLong,nalexander

Depends on D131639

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

browser/base/content/metrics.yaml

@@ -2,5 +2,8 @@
 # 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/.
 
+# Adding a new metric? We have docs for that!
+# https://firefox-source-docs.mozilla.org/toolkit/components/glean/user/new_definitions_file.html
+
 ---
 $schema: moz://mozilla.org/schemas/glean/metrics/2-0-0

gfx/metrics.yaml

@@ -6,6 +6,9 @@
 # automatically converted to platform-specific code at build time using the
 # `glean_parser` PyPI package.
 
+# Adding a new metric? We have docs for that!
+# https://firefox-source-docs.mozilla.org/toolkit/components/glean/user/new_definitions_file.html
+
 ---
 $schema: moz://mozilla.org/schemas/glean/metrics/2-0-0
 

python/mach/metrics.yaml

@@ -4,6 +4,9 @@
 
 # If this file is changed, update the generated docs:
 # https://firefox-source-docs.mozilla.org/mach/telemetry.html#updating-generated-metrics-docs
+
+# Adding a new metric? We have docs for that!
+# https://mozilla.github.io/glean/book/user/metrics/adding-new-metrics.html
 ---
 $schema: moz://mozilla.org/schemas/glean/metrics/1-0-0
 

python/mozbuild/metrics.yaml

@@ -4,6 +4,10 @@
 
 # If this file is changed, update the generated docs:
 # https://firefox-source-docs.mozilla.org/mach/telemetry.html#updating-generated-metrics-docs
+
+# Adding a new metric? We have docs for that!
+# https://mozilla.github.io/glean/book/user/metrics/adding-new-metrics.html
+
 ---
 $schema: moz://mozilla.org/schemas/glean/metrics/1-0-0
 

toolkit/components/glean/docs/user/new_definitions_file.md

@@ -1,13 +1,8 @@
 # New Metrics and Pings
 
-**Note:** FOG is not ready to be used without assistance,
-so you probably should not be adding metrics and pings using this guide yet.
-Instead, please use Firefox Telemetry unless you have explicitly been given permission by a
-[Telemetry Module Peer](https://wiki.mozilla.org/Modules/All#Telemetry).
-
 To add a new metric or ping to Firefox Desktop you should follow the
 [Glean SDK documentation on the subject](https://mozilla.github.io/glean/book/user/adding-new-metrics.html),
-with some few twists.
+with some few twists we detail herein:
 
 ## IPC
 
@@ -34,8 +29,25 @@ to see the list of all currently-known definitions files.
 If you _are_ the first person in your component to ask that question,
 you get to choose where to start them!
 We recommend adding them in the root of your component, next to a `moz.build`.
+Be sure to link to this document at the top of the file!
+It contains many useful tidbits of information that anyone adding new metrics should know.
+Preferably, use this blank template to get started:
 
-When you do so, be sure to edit `toolkit/components/glean/metrics_index.py`,
+```yaml
+# 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/.
+
+# Adding a new metric? We have docs for that!
+# https://firefox-source-docs.mozilla.org/toolkit/components/glean/user/new_definitions_file.html
+
+---
+$schema: moz://mozilla.org/schemas/glean/metrics/2-0-0
+
+```
+
+If you add a new definitions file, be sure to edit
+`toolkit/components/glean/metrics_index.py`,
 adding your definitions files to the Python lists therein.
 If you don't, no API will be generated for your metrics and your build will fail.
 

toolkit/components/glean/metrics.yaml

@@ -6,10 +6,9 @@
 # automatically converted to platform-specific code at build time using the
 # `glean_parser` PyPI package.
 
-# This file is presently for Internal FOG Use Only.
-# You should not add metrics here until probably about January of 2021.
-# If you're looking for the metrics.yaml for Geckoveiw Streaming Telemetry,
-# you can find that one in toolkit/components/telemetry/geckoview/streaming.
+# This file is for Internal FOG Use Only.
+# Please don't add anything here unless you have the permission of a
+# Telemetry Module Peer.
 
 ---
 $schema: moz://mozilla.org/schemas/glean/metrics/2-0-0

toolkit/components/processtools/metrics.yaml

@@ -6,6 +6,9 @@
 # automatically converted to platform-specific code at build time using the
 # `glean_parser` PyPI package.
 
+# Adding a new metric? We have docs for that!
+# https://firefox-source-docs.mozilla.org/toolkit/components/glean/user/new_definitions_file.html
+
 ---
 $schema: moz://mozilla.org/schemas/glean/metrics/2-0-0
 

toolkit/components/telemetry/geckoview/streaming/metrics.yaml

@@ -6,6 +6,9 @@
 # automatically converted to platform-specific code at build time using the
 # `glean_parser` PyPI package.
 
+# Adding a new metric? Please don't!
+# (At least not without the permission of a Telemetry Module Peer)
+
 ---
 $schema: moz://mozilla.org/schemas/glean/metrics/2-0-0
 

toolkit/mozapps/update/metrics.yaml

@@ -2,6 +2,9 @@
 # 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/.
 
+# Adding a new metric? We have docs for that!
+# https://mozilla.github.io/glean/book/user/metrics/adding-new-metrics.html
+
 ---
 $schema: moz://mozilla.org/schemas/glean/metrics/2-0-0