[Discussion] Using git submodule is a bad idea

[T-K-233]

A Reconsider on Git Submodules vs. Monorepo

When this repository was created, we chose to use git submodules to manage the robot asset files and the low-level deployment code that runs on the robot computer.

The original reasoning was mainly two fold:

1. Separation of concerns — Git submodule would provide a separation between the version tree of the training code, the asset (which is quite infrequently updated), and the lowlevel code. As a result, development can be decoupled.
2. Selectively cloning — separating the lowlevel code into its own repository also makes it possible to clone only a subset of the files onto the robot computer.

However, after some time using this setup, both internal developers and external contributors have found that submodules add more friction than benefit:

1. Complex atomic version management — There will be multiple version trees and histories to manage. Especially, when there is coupling between lowlevel ⭤ training code or asset ⭤ training code, it requires special attention to bump the version on two sides to ensure the match.
2. Poor tooling integration — Code search, formatting, and linting across repos need extra config. It is very painful to need opening up all submodules to search functions across tabs on Github.
3. Logistical overhead — The separated repositories also make it harder to administrate. Permission sharing and forking needs to be performed on all the submodules separately, and issues also needs to be tracked multiple places.

The optimal long-term structure is still open for debate, but based on current pain points, a monorepo approach may be more practical.

We’d love to hear perspectives and experiences from others before making a decision. Any thoughts and discussions are greatly appreciated.

[kisg]

A few notes / suggestions:

1. While you are using Git submodules, you could change your .gitmodules files to use relative paths, e.g. ../Berkeley-Humanoid-Lite-Lowlevel.git
   This will allow people to:

• create forks without having to modify the repositories to point to the right submodule repo
• clone the repo using https - some people cannot use SSH towards the internet on their (company) network

2. We usually only use submodules if the components have separate development / release cycles, or are forked from / used by other projects. Components built in the same project are usually better kept in a single repository.