rdr: document the process of hashing new fields added to CrateRoot

Author: susitsm

compiler/rustc_metadata/src/rmeta/encoder/public_api_hasher.rs

@@ -161,6 +161,34 @@ pub(crate) fn hash_crate_root_public_api(
     if !hcx.hash_public_api {
         return;
     }
+    // This must be matched exhaustively to help avoid subtle miscompiles when introducing new data
+    // into rmeta.
+    //
+    // When a new field is added to `CrateRoot` the process of handling it in this function
+    // should be the following:
+    // 1. stable hash the values/query result serialized into the rmeta. For example if a new field
+    //    named `let my_new_field = self.encode_my_new_field();` is added to `CrateRoot` it
+    //    should be added here as
+    //    ```
+    //    // FIXME do we need this                      // or a comment about why we need this
+    //    let _ = my_new_field;
+    //    hasher.digest(tcx.query_my_new_field(), hcx); // or any other code that was that was used
+    //                                                  // to get the encoded value in
+    //                                                  // `encode_my_attribute_list`. We could
+    //                                                  // decode it instead, but that is expensive.
+    //    ```
+    //    if the field was simple enough, like a bool, which does not need to be encoded
+    //    separately:
+    //    ```
+    //    // FIXME do we need this                      // or a comment about why we need this
+    //    hasher.digest(my_new_field);
+    //    ```
+    //
+    // 2. Add the comment "When changed, make sure to update the hashing in
+    //    `hash_crate_root_public_api`" into `encode_my_new_field`
+    // 3. Only remove/change what is hashed in a separate PR. Removing items just from the hash
+    //    should be done with extreme scrutiny. A better way might be to sort the query result
+    //    in its provider, or filter which values we encode. That also helps with rmeta size.
     let CrateRoot {
         header,
         extra_filename,