Merge pull request #4070 from luarss/topic/fix-2213

[docs] add GitGuideAdapter for ORFS docs clarification

Author: vvbandeira

docs/conf.py

@@ -78,6 +78,7 @@
     "docs/releases/PostAlpha2.1BranchMethodology.md",
     "main",
     "index.md",
+    "contrib/GitGuideAdapter.md",
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
@@ -162,14 +163,22 @@ def setup(app):
     url = "https://raw.githubusercontent.com/The-OpenROAD-Project/OpenROAD/master/docs/index.md"
     get_file_from_url(url, "SupportedOS.md")
 
-    # edit OpenROAD to OpenROAD-flow-scripts for GitGuide
+    # Adapt the downloaded GitGuide for ORFS: rename references and inject
+    # ORFS-specific submodule forking instructions from GitGuideAdapter.md.
     with open("contrib/GitGuide.md", "r") as f:
         content = f.read()
+    content = (
+        content.replace(
+            "user/Build.md", "../index.md#build-or-installing-orfs-dependencies"
+        )
+        .replace("OpenROAD", "OpenROAD-flow-scripts")
+        .replace("The-OpenROAD-flow-scripts", "The-OpenROAD")
+    )
+    with open("contrib/GitGuideAdapter.md", "r") as f:
+        adapter_content = f.read()
     content = content.replace(
-        "user/Build.md", "../index.md#build-or-installing-orfs-dependencies"
+        "## Creating a branch", adapter_content + "\n## Creating a branch"
     )
-    content = content.replace("OpenROAD", "OpenROAD-flow-scripts")
-    content = content.replace("The-OpenROAD-flow-scripts", "The-OpenROAD")
     with open("contrib/GitGuide.md", "w") as f:
         f.write(content)
 

docs/contrib/GitGuide.md

@@ -1,3 +1,5 @@
 # Git Quickstart
 
 If you have reached this file on GitHub - please refer to this [link](https://openroad-flow-scripts.readthedocs.io/en/latest/contrib/GitGuide.html) for latest documentation.
+
+For ORFS-specific forking instructions (including forking the OpenROAD submodule), see [GitGuideAdapter.md](./GitGuideAdapter.md).

docs/contrib/GitGuideAdapter.md

@@ -0,0 +1,24 @@
+### Forking OpenROAD
+
+OpenROAD-flow-scripts uses OpenROAD as a Git submodule at `tools/OpenROAD`. When you
+fork OpenROAD-flow-scripts, the submodule URL in `.gitmodules` still points to the
+upstream OpenROAD repository. If your contribution requires changes to OpenROAD, you
+must also fork it and update the submodule remote in your local clone.
+
+1. Fork [OpenROAD](https://github.com/The-OpenROAD-Project/OpenROAD) on GitHub.
+
+2. After cloning your OpenROAD-flow-scripts fork recursively, update the submodule
+   remote to point to your OpenROAD fork:
+
+```shell
+cd tools/OpenROAD
+git remote set-url origin https://github.com/your-user-name/OpenROAD.git
+git remote add upstream https://github.com/The-OpenROAD-Project/OpenROAD.git
+```
+
+3. Verify the remotes are set correctly:
+
+```shell
+git remote -v
+```
+