docs: Clarify external code vendoring (#5597)

2 files changed, 62 insertions, 22 deletions

diff --git a/docs/linking_to_external_code.md b/docs/linking_to_external_code.md
index e03bfdfee..1ec556478 100644
--- a/docs/linking_to_external_code.md
+++ b/docs/linking_to_external_code.md
@@ -41,26 +41,10 @@ default directory is:
 
 ## FAQ
 
-### But what if `https://deno.land/` goes down?
+### How do I import a specific version of a module?
 
-Relying on external servers is convenient for development but brittle in
-production. Production software should always bundle its dependencies. In Deno
-this is done by checking the `$DENO_DIR` into your source control system, and
-specifying that path as the `$DENO_DIR` environmental variable at runtime.
-
-### How can I trust a URL that may change?
-
-By using a lock file (using the `--lock` command line flag) you can ensure
-you're running the code you expect to be. You can learn more about this
-[here](./linking_to_external_code/integrity_checking.md).
-
-### How do you import to a specific version?
-
-Simply specify the version in the URL. For example, this URL fully specifies the
-code being run: `https://unpkg.com/liltest@0.0.5/dist/liltest.js`. Combined with
-the aforementioned technique of setting `$DENO_DIR` in production to stored
-code, one can fully specify the exact code being run, and execute the code
-without network access.
+Specify the version in the URL. For example, this URL fully specifies the code
+being run: `https://unpkg.com/liltest@0.0.5/dist/liltest.js`.
 
 ### It seems unwieldy to import URLs everywhere.
 
@@ -91,3 +75,31 @@ import { assertEquals, runTests, test } from "./deps.ts";
 
 This design circumvents a plethora of complexity spawned by package management
 software, centralized code repositories, and superfluous file formats.
+
+### How can I trust a URL that may change?
+
+By using a lock file (with the `--lock` command line flag), you can ensure that
+the code pulled from a URL is the same as it was during initial development. You
+can learn more about this
+[here](./linking_to_external_code/integrity_checking.md).
+
+### But what if the host of the URL goes down? The source won't be available.
+
+This, like the above, is a problem faced by _any_ remote dependency system.
+Relying on external servers is convenient for development but brittle in
+production. Production software should always vendor its dependencies. In Node
+this is done by checking `node_modules` into source control. In Deno this is
+done by pointing `$DENO_DIR` to some project-local directory at runtime, and
+similarly checking that into source control:
+
+```shell
+# Download the dependencies.
+DENO_DIR=./deno_dir deno cache src/deps.ts
+
+# Make sure the variable is set for any command which invokes the cache.
+DENO_DIR=./deno_dir deno test src
+
+# Check the directory into source control.
+git add -u deno_dir
+git commit
+```
diff --git a/docs/linking_to_external_code/integrity_checking.md b/docs/linking_to_external_code/integrity_checking.md
index 820ea1d2b..91d595cda 100644
--- a/docs/linking_to_external_code/integrity_checking.md
+++ b/docs/linking_to_external_code/integrity_checking.md
@@ -1,5 +1,33 @@
 ## Integrity checking & lock files
 
-Deno can store and check module subresource integrity for modules using a small
-JSON file. Use the `--lock=lock.json` to enable and specify lock file checking.
-To update or create a lock use `--lock=lock.json --lock-write`.
+Deno can store and check subresource integrity for modules using a small JSON
+file. Use the `--lock=lock.json` to enable and specify lock file checking. To
+update or create a lock use `--lock=lock.json --lock-write`.
+
+A typical workflow will look like this:
+
+```ts
+// Add a new dependency to "src/deps.ts", used somewhere else.
+export { xyz } from "https://unpkg.com/xyz-lib@v0.9.0/lib.ts";
+```
+
+```shell
+# Create/update the lock file "lock.json".
+deno cache --lock=lock.json --lock-write src/deps.ts
+
+# Include it when committing to source control.
+git add -u lock.json
+git commit -m "feat: Add support for xyz using xyz-lib"
+git push
+```
+
+Collaborator on another machine -- in a freshly cloned project tree:
+
+```shell
+# Download the project's dependencies into the machine's cache, integrity
+# checking each resource.
+deno cache -r --lock=lock.json src/deps.ts
+
+# Done! You can proceed safely.
+deno test --allow-read src
+```