Introduction

With the introduction of submodule for `gitclone` recipe, we needed to update it on Nexedi ERP5 also at the same time as adding submodule. There are many ways we can start using submodules in ERP5, one of the most basic being moving the large BT5 directories to work as submodule directory. Other cases where we can use submodules can be for WebAssembly files, large data files, etc.

Using Submodules/Creating Submodules

Having submodules in a repository is great and very useful, but if one look in the repository, all we have is an empty folder rather than the actual contents of the submodule’s repository. In order to fill in the submodule’s path with the files from the external repository, you must first initialise the submodules and then update them.

First, we need to initialise the submodule(s). We can do that with the following command. For example throughout this documentation, we are gonna use erp5 as parent repository and bt5-erp5_notebook as submodule.

git submodule init

Then we need to run the update in order to pull down the files.

git submodule update

Cleanly Removing Submodules

What happens if we need to remove a submodule? Maybe I made a mistake. It could also be that the design of the project has changed, and the submodules need to change with it. No problem, I’ll simply run “git submodule rm [submodule path]” and everything will be great, right?

Its a three step process to cleanly remove submodule. This should be explicitly done by the developer itself because it doesn't need to be changed.

# Remove the submodule entry from .git/config
git submodule deinit -f path/to/submodule

# Remove the submodule directory from the superproject's .git/modules directory
rm -rf .git/modules/path/to/submodule

# Remove the entry in .gitmodules and remove the submodule directory located at path/to/submodule
git rm -f path/to/submodule

Updating Submodules

There is an aspect about submodules that some may not realise when first working with Git submodules. When you add the submodule, the most recent commit of the submodule is stored in the main repository’s index. That means that as the code in the submodule’s repository updates, the same code will still be pulled on the repositories relying on the submodule.

This makes a lot of sense when you consider how your code will have been tested and verified (or at least should be) against a specific version of the submodule code, but the main repository’s code may not work well with new submodule updates before the changes are tested.

Unfortunately, like removing submodules, Git does not make it clear how to update a submodule to a later commit. Fortunately though, it’s not that tough.

Initialise the repository’s submodules by running “git submodule init” followed by “git submodule update“.

Checking out between branches

When both branches have different submodules

Checkout between branches which do have different submodules can be hard task to maintain.

When one branch has submodule and another doesn't

git submodule deinit .
git submodule update --init --recursive

Make changes, commit and checkout submodule files

Just go the submodule directory and use git as usual.

See all changes on submodules

git diff --submodule

Update the submodules to the latest changes on their respective branches

git submodule update --remote

ERP5 VCS Submodule Support

To support use of submodule in ERP5, its necessary to have changes in the ERP5 VCS UI. With the first version of using submodules with ERP5 VCS, there are some rules needed to be followed to make it easier for developers at start to get accustomed with it.

1. There should not be nested submodules in the ERP5 repos -  This will help in maintaining and following ERP5 VCS also for the case of ERP5 notebook.
2. Parent should always be ERP5 repo, this is important especially in case we have to search for list of all submodules.

In ERP5VCS, we use commit changes to commit the BT5 changes in 1 step, like here

But with submodule it needs to be done in 2 steps:

1. Commit the changes in the bt5 repository
2. Commit the version up for the bt5 (acting as submodule) in erp5 repo. 

hence, we have an extra checkbox in BusinessTemplate_doVcsCommit to version up the submodule commit in erp5 repository.  Something like this(with better naming):

This will allow to again keep the commit process in single step, difference being that now we will have 2 commits.

For example in ERP5 repo, we will have something like

erp5.git <parent_revision_1>
  bt5/
    erp5_notebook @ <submodule_revision_1>/ (submodule pointing to bt5-erp5_notebook.git)

Now changes in erp5_notebook BT5 and commiting it with ERP5 VCS UI will change the revisions to:

erp5.git <version up erp5_notebook BT5 to submodule_revision_2>
  bt5/
    erp5_notebook @ <submodule_revision_2>/ (submodule pointing to bt5-erp5_notebook.git)

Todo

 - Add more code examples to explain different cases of submodule problems which developers will face.

     - branch checkout b/w with SM and without SM

      - deletion of submodule. DONE

      - Creating submodule commit with ERP5 VCS.

- ERP5 VCS image (https://lab.nexedi.com/nexedi/erp5/merge_requests/832#note_74445) to explain need of interaction workflow while creating commit (fail safe transaction and interaction workflow).

- Add section for naming convention to be followed for submodules (as discussed with Jerome https://lab.nexedi.com/nexedi/erp5/commit/88b6eea4a76b1191463bd6f110fe12b919b1c26d#note_70572)