From 2516dc5eeccb0614b9c9a8fad1a18f37559417bd Mon Sep 17 00:00:00 2001
From: "Hsing-Yu (David) Chen" <davidhsingyuchen@gmail.com>
Date: Wed, 8 Mar 2023 10:55:23 -0800
Subject: [PATCH] docs: make 'git pull' automatically update submodules (#274)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Why

Before this PR, if the pinned commit of any submodule is updated in the
remote tracking branch, folks need to explicitly add `--recurse` when
running `git pull` to also update the submodule to the updated commit.
Regarding our usage of submodules, since we only consume upstream
updates (i.e., not modifying them), and there're not many submodules,
which means that recursively updating them won't take a lot of time,
it's likely that we always want to recursively update all the submodules
when running `git pull`.

## Steps to Reproduce

Setup:

```sh
git clone --recurse-submodules --branch v0.4.0 https://github.com/runfinch/finch.git
cd finch
git checkout -b demo
git branch --set-upstream-to origin/main
git pull
```

Submodules are not updated:

```sh
➜  finch git:(demo) ✗ git --no-pager diff
diff --git a/deps/finch-core b/deps/finch-core
index eef2102..01e6162 160000
--- a/deps/finch-core
+++ b/deps/finch-core
@@ -1 +1 @@
-Subproject commit eef21029b89d7db00bddc6e426e4405c920b13ed
+Subproject commit 01e6162d6fd76fddb9d8ef59845c782a0b6ebafd
```

Fix it:

```sh
➜  finch git:(demo) ✗ git config submodule.recurse true
➜  finch git:(demo) ✗ git pull
Fetching submodule deps/finch-core
Fetching submodule deps/finch-core/src/lima
Fetching submodule deps/finch-core/src/socket_vmnet
Already up to date.
Submodule path 'deps/finch-core': checked out 'eef21029b89d7db00bddc6e426e4405c920b13ed'
Submodule path 'deps/finch-core/src/socket_vmnet': checked out 'ee27d206872fc861c2993264be93d2ccc2740f9c'
➜  finch git:(demo) git --no-pager diff
➜  finch git:(demo) echo $?
0
```

## Notes

If `submodule.stickyRecursiveClone` is set, and the repository is cloned
with `--recurse-submodules`, it'd also work, but it does not account for
the case when the repository is already cloned without
`--recurse-submodules`, so setting `git config submodule.recurse true`
seems to be the simplest way that works for all scenarios.

## License Acceptance

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

Signed-off-by: Hsing-Yu (David) Chen <davidhsingyuchen@gmail.com>
---
 CONTRIBUTING.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 50e451daa..9a727ada5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -139,9 +139,13 @@ If the repo is already cloned, but the submodules are not pulled yet, the follow
 git submodule update --init --recursive
 ```
 
-After cloning the repo, run `make` to build the binary.
+After cloning the repo, run the following command to make subsequent `git pull` to also update submodules to the versions specified in the upstream branch.
 
-The binary in `_output` can be directly used. E.g. initializing the vm and display the version
+```shell
+git config submodule.recurse true
+```
+
+Then run `make` to build the binary. The binary in `_output` can be directly used. E.g. initializing the vm and display the version
 
 ```sh
 ./_output/bin/finch vm init