Refactor submodule documentation

Moved notes on submodules out of contributing guidelines and into
`docs/git/submodules.md` as most developers will touch them infrequently
now.

docs/git/basics.md

@@ -76,8 +76,8 @@ git fetch --all -p
 # you should call this command ONLY from master branch
 git pull origin master
 
-# update submodules
-git submodule update --recursive 
+# update submodules: this checks the submodules out to the commit recorded in the superproject
+git submodule update
 ```
 
 Then switch to your branch and do rebase

docs/git/committing.md

@@ -1,8 +1,14 @@
-#Commit Dance
+Commit Dance
+============
 
-**Update:** commit dance became much simpler after [removing psl-monad submodule](https://github.com/PowerShell/PowerShell/issues/656).
-Meahwhile, there are still few submodules. If you need to touch their content, this doc provides the overview of the process.
-Remember that it's written against `src/monad` submodule, which doesn't exist anymore.
+**Update:** commit dance became much simpler after
+[removing psl-monad submodule](https://github.com/PowerShell/PowerShell/issues/656).
+Thus, this really only applies to `src/windows-build` and
+`src/Modules/Pester`. If you need to touch their content, this doc
+provides the overview of the process. Remember that it's written
+against `src/monad` submodule, which doesn't exist anymore.
+
+Also see the [submodules documentation](./submodules.md).
 
 Sometimes, you need to do the work in a submodule (i.e. you added a new string in `.resx` file).
 The submodule has a relationship to the SuperProject  (PowerShell), but in order to be sure that CI is

docs/git/submodules.md

@@ -0,0 +1,43 @@
+Submodules
+==========
+
+While most developers will not have to deal with submodules on a
+regular basis, those who do should read this information. The
+submodules currently in this project are:
+
+- `src/Modules/Pester`: The Pester testing framework for PowerShell
+
+- `src/libpsl-native/test/googletest`: The GoogleTest framework for
+  Linux native code
+
+- `src/windows-build`: Collection of pre-generated artifacts required
+  until .NET CLI deprecates them (C# resource bindings) and NuGet
+  packages that will soon be moved to a MyGet feed
+
+- `src/omi`: The Open Management Infrastructure project for PSRP on
+  Linux (to be removed)
+
+- `src/omi-provider`: The OMI provider for PSRP on Linux (to be
+  removed)
+
+[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
+
+Rebase and Fast-Forward Merge Pull Requests in Submodules
+=========================================================
+
+*This is not necessary in the superproject, only submodules!*
+
+**DO NOT** commit updates unless absolutely necessary. When submodules
+must be updated, a separate Pull Request must be submitted, reviewed,
+and merged before updating the superproject.
+
+Because GitHub's "Merge Pull Request" button merges with `--no-ff`, an
+extra merge commit will always be created. This is especially annoying
+when trying to commit updates to submodules. Therefore our policy is
+to merge using the Git CLI after approval, with a rebase onto master
+to enable a fast-forward merge.
+
+When committing submodule updates, ensure no other changes are in the
+same commit. Submodule bumps may be included in feature branches for
+ease of work, but the update must be independently approved before
+merging into master.