Git Submodule Best Practices

This guide is not gonna go into detail on what every single git submodule command does, you can just as easily find that on Git’s website

What Are Git Submodules

Lets say your bob and you wanna setup a lemonade stand.

Your lemonade sales are going amazingly well, however you notice on days that aren’t hot you don’t get as many sales.

So instead on those days you sell cookies.

Would it make sense for you to have two separate stands for your lemonades and your cookies

Or would you rather use the same table and chair, but just have different decorations and different products

This is what git submodules allow us to do, they allow us to have common code that is shared between multiple applications without having to rewrite it twice

Back to our analogy lets say you wanted to add a camera to your table and do some cookie/lemonade vlogs, if you weren’t able to share anything between your two stands you’d have to buy two separate cameras, two separate mounts and set it up two separate times.

Git submodules also allows us so that whenever we need to make modifications or bug fixes to our code, we knock out however many applications that use that submodule at once, instead of going into every application and fixing the same thing over and over again

Submodule Quirks

Due to git being a version control software, when we update a submodule, this change does not automatically make update the submodules version in the parent repositories. We need to explicitly tell git to update that submodule in the parent as well. This is something we want because if Scott (Universal Freshman) goes and destroys a driver that both Cerberus and Shepherd are using, Dylan (Universal Senior) won’t have to blow his brains out wondering why his driver randomly stopped working even though no code was updated in Shepherd.

Working With This Version Control

These are best practices I’ve found to work well when dealing with submodules on a large team with multiple working branches at a time.

1. PARENT BRANCHES POINT TO THE SUBMODULE EQUIVALENT OR SENIOR BRANCH

   1. This essentially means if you have a main branch on a parent repository, this branch can only ever point to the main branch in the submodule, since the main branch is the only branch on submodule that is of equivalent or higher level to the parents main branch.

   2. develop may point to either develop or main of a submodule, since develop is equivalent to develop and main is higher than develop. However this does not mean that develop/fsae in a parent can point to develop/fhe in a submodule. develop/fsae can point to develop/fsae, develop or main in the submodule. This also means that develop in a parent should never point to a feature branch in a submodule. The feature branch should be merged into either develop or main in the submodule and the parent then have its submodule updated.

2. HEAD to HEAD

   1. This means that heads of parent branches should always be pointing to the head of submodule branches. So, whenever a change to develop in a submodule is made, all applications using that submodule must have their develop branches updated to match the updated submodule. Same with changes to main.

   2. If you are the author of a PR to a submodule, it is your responsibility to understand where the submodule is being used, and make the appropriate submodule updates in the associated applications branches. This ensures that all changes are understood by maintainers of parent repositories.

   3. Feature branches using a higher level branch do not need to be updated by the author of the submodule change, its the responsibility of the maintainer of that feature branch to update as needed.

3. Parents should review

   1. Ideally a PR should get approvals from maintainers of all parent applications before being merged. This ensures proper understanding of the changes made and how they should affect parent applications so that bugs the maintainers do not understand do not appear.