Parcourir la source

Improve notes on MODULE.bazel.lock changes (#4167)

I admit I'm tempted to make a MODULE.bazel.md for these comments, so
that modifying them doesn't trigger a lockfile update, but I don't
really want it at the top level.
Jon Ross-Perkins il y a 1 an
Parent
commit
1fc488da10
1 fichiers modifiés avec 27 ajouts et 8 suppressions
  1. 27 8
      MODULE.bazel

+ 27 - 8
MODULE.bazel

@@ -4,14 +4,33 @@
 
 """Bazel modules.
 
-If `MODULE.bazel.lock` changes locally, it means the host platform hasn't yet
-been added to the lock file. Running `bazel mod deps` provides a canonical
-update to `MODULE.bazel.lock`; create a PR with those changes in order to
-include the host platform.
-
-Platforms tested with GitHub actions are kept up-to-date. Other platforms may
-fall out of sync on dependency changes, and should be updated with a PR the same
-way a platform is added.
+`MODULE.bazel.lock` may change locally when `bazel` is exexcuted. This means one
+of:
+
+1.  `MODULE.bazel` is changing.
+    -   Running `bazel mod deps` provides a canonical update to
+        `MODULE.bazel.lock`; include the changes.
+    -   GitHub test actions may also identify platform-specific lockfile
+        updates.
+2.  The `bazel` version doesn't match the version used to generate the
+    `MODULE.bazel.lock`.
+    -   Bazel releases can change the lock file contents.
+    -   We use Bazelisk in order to keep everyone using the same version:
+        https://bazel.build/install/bazelisk
+        -   Developers are encouraged to alias `bazel` to `bazelisk` for
+            ease-of-use; some setups, like Homebrew, will include that with a
+            `bazelisk` install.
+        -   Contribution tools documentation includes `bazelisk` setup:
+            https://github.com/carbon-language/carbon-lang/blob/trunk/docs/project/contribution_tools.md
+    -   Make sure `bazelisk --version` (or `bazel --version`) matches the
+        version in `.bazeliskrc`.
+3.  The host platform hasn't yet been added to the lock file.
+    -   Platforms tested with GitHub actions are kept up-to-date. Other
+        platforms may fall out of sync due to `bazel` or dependency changes,
+        and should be updated with a PR the same way a platform is added.
+    -   Running `bazel mod deps` provides a canonical update to
+        `MODULE.bazel.lock`; create a PR with those changes in order to include
+        the host platform.
 """
 
 module(name = "carbon")