chore: updated .aspect/bazelrc/README.md

.aspect/bazelrc/README.md

@@ -1,4 +1,73 @@
 # Aspect Recommended Bazel Options
 
-The Bazel options found here are the source-of-truth for our recommended set of settings.
+The `.bazelrc` files found here are the source-of-truth for our recommended Bazel options.
+
 They are mirrored on our docsite at https://docs.aspect.build/guides/bazelrc.
+
+## Using these Bazel options in your project
+
+To use these files in your project, simply vendor them in and reference them from your `.bazelrc` file.
+
+For example,
+
+```
+# Import Aspect recommended Bazel convenience settings for all projects
+import %workspace%/.aspect/bazelrc/convenience.bazelrc
+
+# Import Aspect recommended Bazel correctness settings for all projects
+import %workspace%/.aspect/bazelrc/correctness.bazelrc
+
+# Import Aspect recommended Bazel performance settings for all projects
+import %workspace%/.aspect/bazelrc/performance.bazelrc
+
+# Import Aspect recommended Bazel debug settings for all projects
+import %workspace%/.aspect/bazelrc/debug.bazelrc
+
+# Import Aspect recommended Bazel javascript settings for all projects
+import %workspace%/.aspect/bazelrc/javascript.bazelrc
+
+# Import Aspect recommended Bazel 6 settings for all projects
+import %workspace%/.aspect/bazelrc/bazel6.bazelrc
+
+### YOUR PROJECT SPECIFIC SETTINGS GO HERE ###
+
+# Load any settings & overrides specific to the current user from `.aspect/bazelrc/user.bazelrc`.
+# This file should appear in `.gitignore` so that settings are not shared with team members. This
+# should be last statement in this config so the user configuration is able to overwrite flags from
+# this file. See https://bazel.build/configure/best-practices#bazelrc-file.
+try-import %workspace%/.aspect/bazelrc/user.bazelrc
+```
+
+## Automatic updates
+
+A convenient way to automatically keep your vendored copy up-to-date is to use
+[`write_source_files`](https://docs.aspect.build/rules/aspect_bazel_lib/docs/write_source_files):
+
+```
+load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
+
+# Keep up-to-date with Aspect recommended .bazelrc settings.
+# See https://github.com/aspect-build/bazel-lib/tree/main/.aspect/bazelrc for the most up to date
+# version of Aspect's recommended Bazel options. These are mirrored on our
+# [docsite](https://docs.aspect.build/guides/bazelrc) for easier consumption.
+write_source_files(
+    name = "update_aspect_recommended_bazel_options",
+    files = {
+        "bazel5.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:bazel5.bazelrc",
+        "bazel6.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:bazel6.bazelrc",
+        "ci.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:ci.bazelrc",
+        "convenience.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:convenience.bazelrc",
+        "correctness.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:correctness.bazelrc",
+        "debug.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:debug.bazelrc",
+        "javascript.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:javascript.bazelrc",
+        "performance.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:performance.bazelrc",
+    },
+)
+```
+
+When `@aspect_bazel_lib` is upgraded in your `WORKSPACE.bazel` or your `MODULE.bazel` file, a `diff_test`
+stamped out by `write_source_files` will fail if your vendored copy is out-of-date and print the Bazel command
+to run to update it. For example, `bazel run //.aspect/bazelrc:aspect_recommended_bazel_options`.
+
+See the [bazelrc](https://github.com/aspect-build/bazel-examples/blob/main/bazelrc/.aspect/bazelrc/BUILD.bazel) example
+in our [bazel-examples](https://github.com/aspect-build/bazel-examples) repository for a working example.