diff --git a/scripts/update b/scripts/update
index 82b7332c0..dfb8008ff 100755
--- a/scripts/update
+++ b/scripts/update
@@ -2,6 +2,13 @@
 #!nix-shell -i bash -p findutils -p git -p nix-update
 
 # each update job has to do an entire nix eval, which can be memory intensive; be careful when tuning this
+# N.B.: not all update jobs are actually independent! naive parallelism like this *will* result in
+# failed/partial updates, e.g.:
+# 1. `sane.nixpkgs-bootstrap.master` is being updated: this breaks eval of _all_ other attributes.
+# 2. `sane.otherPackage` is being updated: its updateScript fails to eval `sane.otherPackage.src`,
+#     however this would eval if job 1 and 2 were serialized.
+#
+# TODO: perform parallel updates in some way that the update scripts don't interfere with eachother.
 PARALLELISM=8
 SELF_PATH=$PWD/$0