change stage0.json to reduce the chance of merge conflicts

Author: pietroalbini

src/stage0.json

@@ -1,11 +1,20 @@
 {
-  "__comment": "Generated by `./x.py run src/tools/bump-stage0`. Run that command again to update the bootstrap compiler.",
   "config": {
     "dist_server": "https://static.rust-lang.org",
     "artifacts_server": "https://ci-artifacts.rust-lang.org/rustc-builds",
     "artifacts_with_llvm_assertions_server": "https://ci-artifacts.rust-lang.org/rustc-builds-alt",
     "git_merge_commit_email": "[email protected]"
   },
+  "__comments": [
+    "The configuration above this comment is editable, and can be changed",
+    "by forks of the repository if they have alternate values.",
+    "",
+    "The section below is generated by `./x.py run src/tools/bump-stage0`,",
+    "run that command again to update the bootstrap compiler.",
+    "",
+    "All changes below this comment will be overridden the next time the",
+    "tool is executed."
+  ],
   "compiler": {
     "date": "2022-05-20",
     "version": "beta"

src/tools/bump-stage0/src/main.rs

@@ -10,6 +10,8 @@ const RUSTFMT_COMPONENTS: &[&str] = &["rustfmt-preview"];
 
 struct Tool {
     config: Config,
+    comments: Vec<String>,
+
     channel: Channel,
     version: [u16; 3],
     checksums: IndexMap<String, String>,
@@ -35,7 +37,13 @@ impl Tool {
 
         let existing: Stage0 = serde_json::from_slice(&std::fs::read(PATH)?)?;
 
-        Ok(Self { channel, version, config: existing.config, checksums: IndexMap::new() })
+        Ok(Self {
+            channel,
+            version,
+            config: existing.config,
+            comments: existing.comments,
+            checksums: IndexMap::new(),
+        })
     }
 
     fn update_json(mut self) -> Result<(), Error> {
@@ -44,9 +52,6 @@ impl Tool {
             format!(
                 "{}\n",
                 serde_json::to_string_pretty(&Stage0 {
-                    comment: "Generated by `./x.py run src/tools/bump-stage0`. \
-                              Run that command again to update the bootstrap compiler."
-                        .into(),
                     compiler: self.detect_compiler()?,
                     rustfmt: self.detect_rustfmt()?,
                     checksums_sha256: {
@@ -56,6 +61,7 @@ impl Tool {
                         self.checksums
                     },
                     config: self.config,
+                    comments: self.comments,
                 })?
             ),
         )?;
@@ -172,9 +178,18 @@ enum Channel {
 
 #[derive(Debug, serde::Serialize, serde::Deserialize)]
 struct Stage0 {
-    #[serde(rename = "__comment")]
-    comment: String,
     config: Config,
+    // Comments are explicitly below the config, do not move them above.
+    //
+    // Downstream forks of the compiler codebase can change the configuration values defined above,
+    // but doing so would risk merge conflicts whenever they import new changes that include a
+    // bootstrap compiler bump.
+    //
+    // To lessen the pain, a big block of comments is placed between the configuration and the
+    // auto-generated parts of the file, preventing git diffs of the config to include parts of the
+    // auto-egenrated content and vice versa. This should prevent merge conflicts.
+    #[serde(rename = "__comments")]
+    comments: Vec<String>,
     compiler: Stage0Toolchain,
     rustfmt: Option<Stage0Toolchain>,
     checksums_sha256: IndexMap<String, String>,