diff --git a/docs/conf.py b/docs/conf.py index 97a273842d..e1c9512fdb 100644 --- a/docs/conf.py +++ b/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) diff --git a/docs/contrib/GitGuide.md b/docs/contrib/GitGuide.md index add267ee55..0e57850b9c 100644 --- a/docs/contrib/GitGuide.md +++ b/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). diff --git a/docs/contrib/GitGuideAdapter.md b/docs/contrib/GitGuideAdapter.md new file mode 100644 index 0000000000..5e40639e6f --- /dev/null +++ b/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 +``` +