diff --git a/src/content/docs/troubleshooting.mdx b/src/content/docs/troubleshooting.mdx
index 93cbc31b..1c64cdf8 100644
--- a/src/content/docs/troubleshooting.mdx
+++ b/src/content/docs/troubleshooting.mdx
@@ -237,6 +237,16 @@ This can be caused by a number of things. The most common causes are:
    use caution when publishing patches that include changes to native code from
    plugins. In the worst case, these changes may cause your patched app to
    crash.**
+   :::tip
+   Add your `pubspec.lock` file to version control so you're always aware of
+   updates to your dependencies.
+
+   Versioning your `pubspec.lock` file ensures changes to transitive
+   dependencies are explicit. Each time the dependencies change due to
+   `dart pub upgrade` or a change in `pubspec.yaml`, the difference will be
+   apparent in the lock file.
+   :::
+
 2. A dependency/plugin produces a different output on every build. This can
    happen if the dependency it includes a timestamp indicating when it was
    built, for example. This kind of change is usually safe to publish, but you