From a355bcbd7397be526efc9c54616ecaf4d7b05f34 Mon Sep 17 00:00:00 2001
From: Edward Chen <18449977+edgchen1@users.noreply.github.com>
Date: Thu, 4 Nov 2021 16:23:52 -0700
Subject: [PATCH] Clarify cgmanifest.json update process. (#9664)

---
 cgmanifests/README.md                         | 22 ++++++++++++-------
 ...e_cgmanifest.py => generate_cgmanifest.py} |  9 ++++----
 cgmanifests/generated/README.md               |  2 ++
 .../{submodules => generated}/cgmanifest.json |  0
 .../{submodules => }/print_submodule_info.py  |  0
 5 files changed, 21 insertions(+), 12 deletions(-)
 rename cgmanifests/{submodules/generate_submodule_cgmanifest.py => generate_cgmanifest.py} (92%)
 create mode 100644 cgmanifests/generated/README.md
 rename cgmanifests/{submodules => generated}/cgmanifest.json (100%)
 rename cgmanifests/{submodules => }/print_submodule_info.py (100%)

diff --git a/cgmanifests/README.md b/cgmanifests/README.md
index 1581c91edf..7ff7914d8d 100644
--- a/cgmanifests/README.md
+++ b/cgmanifests/README.md
@@ -1,21 +1,27 @@
 # CGManifest Files
 This directory contains CGManifest (cgmanifest.json) files.
-See here for details: https://docs.opensource.microsoft.com/tools/cg/cgmanifest.html
+See [here](https://docs.opensource.microsoft.com/tools/cg/cgmanifest.html) for details.
 
-`cgmanifests/cgmanifest.json` contains entries that don't belong in more specific categories (e.g., git submodules).
+## `cgmanifests/generated/cgmanifest.json`
+This file contains generated CGManifest entries.
 
-## Git Submodules
-`cgmanifests/submodules/cgmanifest.json` contains entries for git submodules.
-It can be generated like this:
+It covers these dependencies:
+- git submodules
+- dependencies from the Dockerfile `tools/ci_build/github/linux/docker/Dockerfile.manylinux2014_cuda11`
 
+If any of these dependencies change, this file should be updated.
+**When updating, please regenerate instead of editing manually.**
+
+### How to Generate
 1. Change to the repository root directory.
-2. Ensure the submodules are checked out. For example, with:
+2. Ensure the git submodules are checked out and up to date. For example, with:
     ```
     $ git submodule update --init --recursive
     ```
 3. Run the generator script:
     ```
-    $ python cgmanifests/submodules/generate_submodule_cgmanifest.py > cgmanifests/submodules/cgmanifest.json
+    $ python cgmanifests/generate_cgmanifest.py
     ```
 
-Please update this cgmanifest.json file when any git submodules change.
+## `cgmanifests/cgmanifest.json`
+This file contains non-generated CGManifest entries. Please edit directly as needed.
diff --git a/cgmanifests/submodules/generate_submodule_cgmanifest.py b/cgmanifests/generate_cgmanifest.py
similarity index 92%
rename from cgmanifests/submodules/generate_submodule_cgmanifest.py
rename to cgmanifests/generate_cgmanifest.py
index df6d5f0df6..bb27bfd768 100644
--- a/cgmanifests/submodules/generate_submodule_cgmanifest.py
+++ b/cgmanifests/generate_cgmanifest.py
@@ -2,12 +2,12 @@
 
 import json
 import os
+import re
 import subprocess
 import sys
-import re
 
 SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__))
-REPO_DIR = os.path.normpath(os.path.join(SCRIPT_DIR, "..", ".."))
+REPO_DIR = os.path.normpath(os.path.join(SCRIPT_DIR, ".."))
 
 package_name = None
 package_filename = None
@@ -16,7 +16,7 @@ package_url = None
 registrations = []
 
 with open(os.path.join(REPO_DIR, 'tools', 'ci_build', 'github', 'linux', 'docker', 'Dockerfile.manylinux2014_cuda11'),
-          "r") as f:
+          mode="r") as f:
     for line in f:
         if not line.strip():
             package_name = None
@@ -95,4 +95,5 @@ for submodule_line in submodule_lines:
 
 cgmanifest = {"Version": 1, "Registrations": registrations}
 
-print(json.dumps(cgmanifest, indent=2))
+with open(os.path.join(SCRIPT_DIR, "generated", "cgmanifest.json"), mode="w") as generated_cgmanifest_file:
+    print(json.dumps(cgmanifest, indent=2), file=generated_cgmanifest_file)
diff --git a/cgmanifests/generated/README.md b/cgmanifests/generated/README.md
new file mode 100644
index 0000000000..299ce4bc82
--- /dev/null
+++ b/cgmanifests/generated/README.md
@@ -0,0 +1,2 @@
+`cgmanifests/generated/cgmanifest.json` is a generated file. Please do not edit it directly.
+More info [here](../README.md).
diff --git a/cgmanifests/submodules/cgmanifest.json b/cgmanifests/generated/cgmanifest.json
similarity index 100%
rename from cgmanifests/submodules/cgmanifest.json
rename to cgmanifests/generated/cgmanifest.json
diff --git a/cgmanifests/submodules/print_submodule_info.py b/cgmanifests/print_submodule_info.py
similarity index 100%
rename from cgmanifests/submodules/print_submodule_info.py
rename to cgmanifests/print_submodule_info.py