Update the document, `update_spirv.md` (#5368)

This commit updates the document about how to update the SPIRV submodules.

1 files changed, 143 insertions, 25 deletions

diff --git a/docs/update_spirv.md b/docs/update_spirv.md
index 8463da343..6994b3fa4 100644
--- a/docs/update_spirv.md
+++ b/docs/update_spirv.md
@@ -7,55 +7,99 @@ There are three directories under `external` that are related to SPIR-V:
 
 In order to use the latest or custom SPIR-V, they need to be updated.
 
-## Update URLs to the repo
 
-Open `.gitmodules` and update the following sections to have a desired `url` set.
+## Fork `shader-slang/SPIRV-Tools` repo and update it
+
+Currently Slang uses [shader-slang/SPIRV-Tools](https://github.com/shader-slang/SPIRV-Tools) forked from [KhronosGroup/SPIRV-Tools](https://github.com/KhronosGroup/SPIRV-Tools).
+In order for Slang to use the latest changes from `KhronosGroup/SPIRV-Tools`, `shader-slang/SPIRV-Tools` needs to be updated.
+
+1. Fork `shader-slang/SPIRV-Tools` to your personal github organization like `your-name/SPIRV-Tools`.
+1. Clone it on your local machine.
+   ```
+   git clone https://github.com/your-name/SPIRV-Tools.git # replace `your-name` to the actual URL
+   ```
+1. Fetch from `KhronosGroup/SPIRV-Tools`.
+   ```
+   git remote add khronos https://github.com/KhronosGroup/SPIRV-Tools.git
+   git fetch khronos
+   ```
+1. Create a branch for a Pull Request.
+   ```
+   git checkout -b merge/update
+   ```
+1. Rebase to khronos/main
+   ```
+   git rebase khronos/main # use ToT
+   ```
+1. Push to Github.
+   ```
+   git push origin merge/update
+   ```
+
+The steps above will create a branch called `merge/update`. You can use a different name but this document will use the name.
+
+
+## Test the branch before creating a Pull Request
+
+Before creating a Pull Request, it will be a good idea to test if it works.
+But if you are confident, you may skip the testing step.
+
+
+### Modify `.gitmodules` and use the `merge/update` branch
+
+On a Slang repo side, you need to create a branch for the following changes.
+```
+git clone https://github.com/your-name/slang.git # replace `your-name` to the actual URL
+cd slang
+git checkout -b update_spirv
+```
+
+Open `.gitmodules` and modify the setting to the following,
 ```
 [submodule "external/spirv-tools"]
 	path = external/spirv-tools
-	url = https://github.com/shader-slang/SPIRV-Tools.git
+	url = https://github.com/your-name/SPIRV-Tools.git
 [submodule "external/spirv-headers"]
 	path = external/spirv-headers
 	url = https://github.com/KhronosGroup/SPIRV-Headers.git
 ```
+Note that you need to replace `your-name` with the actual URL from the previous step.
 
-Run the following command to apply the change.
+Apply the URL changes with the following commands,
 ```
 git submodule sync
 git submodule update --init --recursive
-```
 
-If you need to use a specific branch from the repos, you need to manually checkout the branch.
-```
-cd external/spirv-tools
-git checkout branch_name_to_use
+cd spirv-headers
+git fetch
+git checkout origin/main # use ToT
 cd ..
-git add spirv-tools
 
-cd external/spirv-headers
-git checkout branch_name_to_use
-cd ..
-git add spirv-headers
+cd external
+cd spirv-tools
+git fetch
+git checkout merge/update # use merger/update branch
 ```
 
-## Build spirv-tools
+
+### Build spirv-tools
 
 A directory, `external/spirv-tools/generated`, holds a set of files generated from spirv-tools directory.
 You need to build spirv-tools in order to generate them.
 
 ```
-cd external/spirv-tools
-python3.exe utils/git-sync-deps # this step may require you to register your ssh public key to gitlab.khronos.org
-mkdir build
-cd build
-cmake.exe ..
-cmake.exe --build . --config Release
+cd external
+cd spirv-tools
+python3.exe utils\git-sync-deps # this step may require you to register your ssh public key to gitlab.khronos.org
+cmake.exe . -B build
+cmake.exe --build build --config Release
 ```
 
-## Copy the generated files from spirv-tools
 
-Copy some of generated files from `external/spirv-tools/build/` to `external/spirv-tools-generated`.
-The following files are ones you need to copy at the momment, but the list will change in the future.
+### Copy the generated files from `spirv-tools` to `spirv-tools-generated`
+
+Copy some of generated files from `external/spirv-tools/build/` to `external/spirv-tools-generated/`.
+The following files are ones you need to copy at the momment, but the list may change in the future.
 ```
 DebugInfo.h
 NonSemanticShaderDebugInfo100.h
@@ -73,10 +117,84 @@ nonsemantic.vkspreflection.insts.inc
 opencl.debuginfo.100.insts.inc
 opencl.std.insts.inc
 operand.kinds-unified1.inc
-options-pinned.h
 spv-amd-gcn-shader.insts.inc
 spv-amd-shader-ballot.insts.inc
 spv-amd-shader-explicit-vertex-parameter.insts.inc
 spv-amd-shader-trinary-minmax.insts.inc
 ```
 
+
+### Build Slang and run slang-test
+
+There are many ways to build Slang executables. Refer to the [document](https://github.com/shader-slang/slang/blob/master/docs/building.md) for more detail.
+For a quick reference, you can build with the following commands,
+```
+cmake.exe --preset vs2019
+cmake.exe --build --preset release
+```
+
+After building Slang executables, run `slang-test` to see all tests are passing.
+```
+set SLANG_RUN_SPIRV_VALIDATION=1
+build\Release\bin\slang-test.exe -use-test-server -server-count 8
+```
+
+It is often the case that some of tests fail at this step, because of the changes on SPIRV-Header side.
+You need to properly resolve them before proceed.
+
+
+## Create A Pull Request on `shader-slang/SPIRV-Tools`
+
+After testing is done, you should create a Pull Request on `shader-slang/SPIRV-Tools` repo.
+
+1. The git-push command will show you a URL for creating a Pull Request like following,
+   > https://github.com/your-name/SPIRV-Tools/pull/new/merge/update # replace `your-name` to the actual URL
+
+   Create a Pull Request.
+1. Wait for all workflows to pass.
+1. Merge the PR and take a note of the commit ID for the next step.
+
+Note that this process will update `shader-slang/SPIRV-Tools` repo, but your merge is not used by `slang` repo yet.
+
+
+## Create a Pull Request on `shader-slang/slang`
+
+After the PR is merged to `shader-slang/SPIRV-Tools`, `slang` needs to start using it.
+
+On the clone of Slang repo, revert the changes in `.gitmodules` if modified.
+```
+# revert the change in .gitmodules
+git checkout .gitmodules
+git submodule sync
+git submodule update --init --recursive
+```
+
+You need to stage and commit the latest commit IDs of spirv-tools and spirv-headers.
+```
+cd external
+
+# Add changes in spirv-tools-generated
+git add spirv-tools-generated
+
+# Add commit ID of spirv-headers
+cd spirv-headers
+git fetch
+git checkout origin/main # Use ToT
+cd ..
+git add spirv-headers
+
+# Add commit ID of spirv-tools
+cd spirv-tools
+git fetch
+git checkout merge/update # Use merge/update branch
+cd ..
+git add spirv-tools
+
+# Add more if there are other changes to resolve the test failures.
+
+git commit
+git push origin update_spirv
+```
+Once all changes are pushed to GitHub, you can create a Pull Request on `shader-slang/slang`.
+
+