From f8e7a9ec68877fc9343083329fd6078e5210af6a Mon Sep 17 00:00:00 2001
From: Chase Naples <Cnaples79@gmail.com>
Date: Fri, 20 Feb 2026 19:44:21 -0500
Subject: [PATCH] docs: note OpenROAD fork requirement

Signed-off-by: Chase Naples <Cnaples79@gmail.com>
---
 README.md                |  4 ++++
 docs/contrib/GitGuide.md | 44 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 177c240986..75c6a28b37 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,10 @@ timeline
 
 There are multiple ways to install and develop OpenROAD and ORFS. However, the best option depends on your use case, experience level, and personal preference.
 
+```{note}
+Forking ORFS? Also fork [`OpenROAD`](https://github.com/The-OpenROAD-Project/OpenROAD) and point the `tools/OpenROAD` submodule at your fork (e.g., `git submodule set-url tools/OpenROAD https://github.com/<you>/OpenROAD.git && git submodule update --init --recursive`). Otherwise a forked clone may fail to build.
+```
+
 
 > **Recommendation for new users:**  
 > If you are new to OpenROAD-flow-scripts, Docker can be a reliable way to get started since it avoids most dependency and environment issues.  
diff --git a/docs/contrib/GitGuide.md b/docs/contrib/GitGuide.md
index add267ee55..680153b7f9 100644
--- a/docs/contrib/GitGuide.md
+++ b/docs/contrib/GitGuide.md
@@ -1,3 +1,43 @@
-# Git Quickstart
+# Git Quickstart (forks)
 
-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.
+If you are working from your **own fork**, you must fork both this repository **and** the
+`OpenROAD` submodule. Otherwise `git submodule` will still point to the upstream
+`The-OpenROAD-Project/OpenROAD` and builds in your fork will fail.
+
+## Fork + clone
+
+1. Fork **OpenROAD-flow-scripts**.
+2. Fork **OpenROAD** (the tools submodule).
+3. Clone your ORFS fork with submodules:
+   ```bash
+   git clone --recursive https://github.com/<you>/OpenROAD-flow-scripts.git
+   cd OpenROAD-flow-scripts
+   ```
+
+## Point the submodule at your OpenROAD fork
+
+Run these once in your clone:
+
+```bash
+git submodule set-url tools/OpenROAD https://github.com/<you>/OpenROAD.git
+git submodule update --init --recursive
+```
+
+## Keep both forks in sync
+
+```bash
+git remote add upstream https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts.git
+git remote add upstream-or https://github.com/The-OpenROAD-Project/OpenROAD.git
+git fetch upstream upstream-or
+
+# Update ORFS
+git checkout master
+git pull upstream master
+
+# Update OpenROAD submodule to upstream
+git submodule update --remote tools/OpenROAD
+git push origin master
+```
+
+With this setup, `git clone --recursive <your-orfs-fork>` will work, and the submodule
+will track your OpenROAD fork by default.