[docs] Improve dependency and git submodules docs

Add information about adding a new dependency, and clarify how to address
a merge conflict.

R=dcheng, estaab

Change-Id: Ife34d8cb17937db39c592f73741a9888a0742063
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4814410
Reviewed-by: Erik Staab <estaab@chromium.org>
Commit-Queue: Josip Sokcevic <sokcevic@chromium.org>
Reviewed-by: Daniel Cheng <dcheng@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1188805}

docs/dependencies.md

@@ -9,6 +9,17 @@ gclient supports two dependency types: git and [cipd](cipd_and_3pp.md).
 
 [TOC]
 
+## Adding dependencies
+
+Add your entry in DEPS file. Then, run `gclient gitmodules` to generate
+git submodules (it will contain .gitmodule change, and gitlink). Edit OWNERS
+file and add gitlink path. For example, if new dependency is "src/foo/bar.git",
+its gitlink path is "foo/bar". You can confirm that by running `git status`.
+
+Then, run `git add DEPS OWNERS` to stage those files for commit, followed by
+`git commit`. Your change is now ready to be sent for a review using `git cl
+upload`.
+
 ## Rolling dependencies
 
 ### Using gclient

docs/git_submodules.md

@@ -8,6 +8,9 @@ In 2023Q3, we started to move source of Git dependencies from DEPS files to Git
 submodules. While we do our best to hide complexities of submodules, some will
 be exposed.
 
+IMPORTANT NOTE: Due to a bug in fsmonitor, we encourage you to disable it until
+the underlying bug is fixed. More details in https://crbug.com/1475405.
+
 [TOC]
 
 ## A quick introduction to Git submoduldes
@@ -139,10 +142,13 @@ restore --staged <path to submodule>`.
 We will need to create either a commit that sets it back to old value, or amend
 the commit that added it. You can try to run `gclient sync` to bring the commit
 back to what is expected. If that doesn't work, you can use `gclient setdep -r
-<path>@{old hash}`, run `gclient gitmodules` to sync all submodules commits back
+<path>@<old hash>`, run `gclient gitmodules` to sync all submodules commits back
 to what is in DEPS, or check detailed instructions in [Managing
 dependencies](dependencies.md).
 
+NOTE: setdep for chromium/src is always prefixed with src/. For example, if you
+are updating v8, the command would be `gclient setdep -r src/v8@<hash>.
+
 ## FAQ
 
 ### Why do we have Git dependencies in both DEPS and Git submodules?
@@ -152,8 +158,27 @@ massive switch, it's easier to transition to Git submodules this way. Moreover,
 unwanted Git submodule updates can be detected and developers can be warned.
 
 ### How do I manually roll Git submodule?
+
 See the [dependencies](dependencies.md) page.
 
+### I got a conflict on a submodule, how do I resolve it?
+
+First, you will need to determine what is the right commit hash. If you
+accidentally committed a gitlink, which got in the meantime updated, you most
+likely want to restore the original updated gitlink. You can run `gclient
+gitmodules`, which will take care of all unmerged submodule paths, and set it to
+match DEPS file.
+
+If you prefer to manually resolve it, under git status, you will see "Unmerged
+paths". If those are submodules, you want to restore them by running the
+following command:
+
+```
+git restore --staging <affected path>
+```
+
+If you want to keep your gitlink, then run `git add <affected path>`.
+
 ### How can I provide feedback?
 
 Please file [a bug under Infra>SDK