tools: add more details about rolling inspector_protocol

legendecas · web-flow · commit f37d2a580913 · 2025-03-04T12:13:28.000Z
PR-URL: #57167 Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
diff --git a/doc/contributing/maintaining/maintaining-dependencies.md b/doc/contributing/maintaining/maintaining-dependencies.md
@@ -19,6 +19,7 @@ This a list of all the dependencies:
 * [googletest][]
 * [histogram][]
 * [icu-small][]
+* [inspector\_protocol][inspector_protocol]
 * [libuv][]
 * [llhttp][]
 * [minimatch][]
@@ -272,6 +273,12 @@ and Java libraries providing Unicode and Globalization
 support for software applications.
 See [maintaining-icu][] for more information.
 
+### inspector\_protocol
+
+The [inspector\_protocol](https://chromium.googlesource.com/deps/inspector_protocol/)
+is Chromium's of code generators and templates for the inspector protocol.
+See [this doc](../../../tools/inspector_protocol/README.md) for more information.
+
 ### libuv
 
 The [libuv](https://github.com/libuv/libuv) dependency is a
@@ -411,6 +418,7 @@ according to [RFC 8878](https://datatracker.ietf.org/doc/html/rfc8878).
 [googletest]: #googletest
 [histogram]: #histogram
 [icu-small]: #icu-small
+[inspector_protocol]: #inspector_protocol
 [libuv]: #libuv
 [llhttp]: #llhttp
 [maintaining-V8]: ./maintaining-V8.md
diff --git a/tools/inspector_protocol/README.md b/tools/inspector_protocol/README.md
@@ -1,6 +1,37 @@
 # Chromium inspector (devtools) protocol
 
-This directory contains scripts to update the [Chromium inspector protocol][]
+This directory contains scripts to update the [Chromium `inspector_protocol`][]
 to local at `deps/inspector_protocol`.
 
-[Chromium inspector protocol]: https://chromium.googlesource.com/deps/inspector_protocol/
+To run the `roll.py`, a local clone of the `inspector_protocol` project is required.
+First, you will need to install Chromium's [`depot_tools`][], with `fetch` available
+in your `PATH`.
+
+```console
+$ cd workspace
+/workspace $ mkdir inspector_protocol
+/workspace/inspector_protocol $ fetch inspector_protocol
+# This will create a `src` directory in the current path.
+
+# To update local clone.
+/workspace/inspector_protocol $ cd src
+/workspace/inspector_protocol/src $ git checkout main && git pull
+```
+
+With a local clone of the `inspector_protocol` project up to date, run the following
+commands to roll the dep.
+
+```console
+$ cd workspace/node
+/workspace/node $ python tools/inspector_protocol/roll.py \
+  --ip_src_upstream /workspace/inspector_protocol/src \
+  --node_src_downstream /workspace/node \
+  --force
+  # Add --force when you decided to take the update.
+```
+
+The `roll.py` requires the node repository to be a clean state (no unstaged changes)
+to avoid unexpected overrides.
+
+[`depot_tools`]: https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up
+[Chromium `inspector_protocol`]: https://chromium.googlesource.com/deps/inspector_protocol/
