Contributing docs: explain compat_features versus tags (#1667)

* Contributing docs: explain `compat_features` versus tags

Fixes #1633

* Make "YAML wins" logic more explicit

* Apply clarification on yml to dist

Co-authored-by: James Stuckey Weber <[email protected]>

* Elaborate on authored YAML to dist file relationship

---------

Co-authored-by: James Stuckey Weber <[email protected]>

Author: ddbeck

Diff for: docs/CONTRIBUTING.md

@@ -78,7 +78,7 @@ This table lists the fields that can be found in a feature file, and provides a
 | `spec` | One or more specification URLs for this feature. | String, or array of strings | Yes |
 | `group` | An optional group, or list of groups that this feature belongs to. See the definition of groups under [Create a new feature from scratch](#create-a-new-feature-from-scratch). | String, or array of strings | No |
 | `caniuse` | The feature's ID on the [Can I Use](https://caniuse.com/) website. | String | No |
-| `compat_features` | The list of browser-compat-data entries that make up this feature. In many cases, the corresponding browser-compat-data entries already map to the feature ID, and this is therefore not needed. | Array of strings | No |
+| `compat_features` | @mdn/browser-compat-data (BCD) entry keys (e.g., `css.properties.background-color`) that make up this feature. If `compat_features` is not set in `<feature-id>.yml`, the `dist` script will populate `compat_features` in `<feature-id>.yml.dist` with BCD entry keys tagged with `web-features:<feature-id>` in BCD, if any exist. | Array of strings | No |
 | `status` | An optional object which describes whether the feature is considered baseline, when it achieved this baseline status, and the version number of supported browsers. In the majority of cases, this is calculated from the `compat_features` list or from browser-compat-data entries directly, and therefore not needed. | Object | No |
 | `status.compute_from` | An optional field, within the `status` object, to allows you to specify which BCD keys should the overall feature status be computed from. This is useful to list all BCD keys that are related to a feature, but only consider some of them in the baseline status calculation. | String, or array of strings | No |
 
@@ -90,7 +90,18 @@ Dist files are also YAML files, but they end with the `.yml.dist` extension. Dis
 
 For example, the `fetch` feature file is `features/fetch.yml`, and its dist file is `features/fetch.yml.dist`.
 
-You **never edit a dist file** directly. Dist files are generated from the authored YAML files, and are used at build time to generate the final data bundle that's used by other projects. Dist files are generated by using the `npm run dist` command, which you use when creating or updating a feature. If the dist file contains only an empty object (`{}`) it means that there is no generated data in addition to the source YAML. To learn more, see [Set the status of a feature](#set-the-status-of-a-feature), below.
+You **never edit a dist file** directly. Dist files are generated from the authored YAML files, and are used at build time to generate the final data bundle that's used by other projects.
+
+To generate a dist file, run `npm run dist` command.
+Do this when creating or updating a feature.
+
+Some fields, such as `status` and `compat_features`, may appear in either the authored YAML file, the generated dist file, or both.
+The contents of the authored YAML file overrules all other implicit sources of data.
+For example, if you set `compat_features` in an authored YAML file, then the corresponding @mdn/browser-compat-data tag is ignored.
+Likewise, setting a `status` value in an authored YAML file overrules a status generated from `compat_features` or tag.
+
+If the dist file contains only an empty object (`{}`) it means that there is no generated data in addition to the source YAML.
+To learn more, see [Set the status of a feature](#set-the-status-of-a-feature), below.
 
 > [!Important]
 > Even if dist files are generated artifacts, they are still checked-in to the repository. This is normal and expected. Because dist files contain the compatibility data and status information for a feature, we review them as part of the pull request process.