docs/design/git-submodules.md

@@ -166,31 +166,33 @@ submodules _are_ standalone Git repositories:
 We should keep in mind that a submodule exists to be integrated with a
 superproject, otherwise, the submodule could just be an independent clone. As
 such, jj should enforce tight integrations between superproject and submodule
-tightly by requiring that all interactions with the submodule must be initiated
+by requiring that all interactions with the submodule must be initiated
 from the superproject.
 
 #### Commands should involve submodules by default
 
-Git does not recurse into submodules by default (it requires the
-`--recurse-submodules` flag or the `submodule.recurse` config setting), and this
-is a constant source of confusion for users, e.g.:
+Submodules should be part of the 'regular' jj workflow. Users shouldn't have to
+remember to tell jj to consider submodules and manual submodule management
+should be reserved only for very exceptional cases. For example,
 
-- Non-recursive `git clone` will not clone submodules, resulting in their
-  contents being unpopulated in the working tree.
+- `jj git clone` should clone a 'reasonable' set of submodules.
 
-- Non-recursive `git checkout` does not update the submodule index or working
-  tree, resulting in the submodule being 'dirty' and the working tree being out
-  of sync with the superproject.
+- Updating the working copy in the superproject should also update the submodule
+  working copies.
 
-We should always consider submodules. If they are ignored, we should be explicit
-to the user.
+Contrast these with Git, where the `--recurse-submodules` needs to be explicitly
+passed, and is a constant source of confusion for users.
+
+In exceptional cases, submodules might be excluded (e.g. a submodule remote
+deletes the commits we rely on). We should anticipate these problems, recover
+gracefully, and be explicit to the user.
 
 #### Submodules are globally managed
 
 In a regular jj or Git repository, objects are reusable because they are stored
-in a central database, regardless of the working copy. Similarly, we should
-manage submodules globally and treat that as the source of truth; the working
-copy should, at best, be treated as a hint.
+in a database independent of the working copy. Similarly, we should manage
+submodules globally and treat that as the source of truth; the working copy
+should, at best, be treated as a hint.
 
 A consequence of this is that it is expected that the working copy may be out
 of sync with the global submodules, e.g. submodules may be missing, their