Add section about stray files (#6274)

In support of dart-lang/pub#4446

---------

Co-authored-by: Eric Windmill <[email protected]>
Co-authored-by: Marya <[email protected]>

firebase.json

@@ -179,6 +179,7 @@
       { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 },
       { "source": "/go/macros", "destination": "/language/macros", "type": 301 },
       { "source": "/go/pub-workspaces", "destination": "/tools/pub/workspaces", "type": 301 },
+      { "source": "/go/workspaces-stray-files", "destination": "/guides/workspaces#stray-files", "type": 301 },
       { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons#getter-name", "type": 301 },
       { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons#field-name", "type": 301 },
       { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons#nosuchmethod", "type": 301 },

src/content/tools/pub/workspaces.md

@@ -107,6 +107,47 @@ To use pub workspaces, all your workspace packages (but not your dependencies)
 must have an SDK version constraint of `^3.6.0` or higher.
 :::
 
+<a name='stray-files'></a>
+## Stray files
+
+When you migrate an existing monorepo to use Pub workspaces, there will
+be existing "stray" `pubspec.lock` and `.dart_tool/package_config.json` files
+adjacent to each pubspec. These shadow the `pubspec.lock` and
+`.dart_tool/package_config.json` files placed next to the root.
+
+Therefore, `pub get` will delete any `pubspec.lock` and
+`.dart_tool/package_config.json` located in directories between the root and
+(including) any workspace package.
+
+```plaintext
+/
+  pubspec.yaml                       # Root
+  packages/
+    pubspec.lock                     # Deleted by `pub get`
+    .dart_tool/package_config.json   # Deleted by `pub get`
+    foo/
+      pubspec.yaml                   # Workspace member
+      pubspec.lock                   # Deleted by `pub get`
+      .dart_tool/package_config.json # Deleted by `pub get`
+```
+
+If any directory between the workspace root and a workspace package contains a
+"stray" `pubspec.yaml` file that is not member of the workspace, `pub get` will
+report an error and fail to resolve. This is because resolving such a `pubspec.yaml` would
+create a `.dart_tool/package_config.json` file that shadows the one at the root.
+
+For example:
+
+```plaintext
+/
+  pubspec.yaml                      # Root `workspace: ['foo/']`
+  packages/
+    pubspec.yaml                    # Not workspace member => error
+    foo/
+      pubspec.yaml                  # Workspace member
+```
+
+
 ## Interdependencies between workspace packages
 
 If any of the workspace packages depend on each other, they will automatically