Dealing with submodules
Contents
Heavy usage of submodules
The Unvanquished repository makes heavy usage of submodules, and submodules having submodules.
Most of the time, developers don't have to commit the submodules themselves. A submodule change that doesn't break compatibility does not strictly require to be committed.
Please don't commit submodules in pull requests, as the submodules references may not exist after the pull requests are rebased and merged.
When a feature is split across more than one repository, submodules are expected to be committed after each pull requests have been merged.
This happens for example if a pull request is split between Unvanquished/ and Unvanquished/daemon/. The daemon/ submodule is committed after pull-requests for both repositories are merged.
For a method of working that prevents to mistakenly commits submodule changes, follow those instructions.
Ignoring submodules by default when diffing and committing
If you're contributing to the Unvanquished game, the parent repository is Unvanquished/. If you only contribute to the the Dæmon engine and the Dæmon repository is not a submodule, the parent repository is Daemon/.
In parent repository type this command:
git config diff.ignoreSubmodules all
This will remove all submodule changes from git diff and never commit any submodule change when doing git commit -am “message”.
Purposedly diffing and committing submodule changes
To explicitly list submodule changes and commit them you can then do:
git -c diff.ignoreSubmodules=none diff git -c diff.ignoreSubmodules=none commit -am ”message”
Doing a splitted pull-request
You need to do a splitted pull-request if you have changes in multiples repositories and requiring each others.
You will have to be a developer with repository write access, and you will have to push your branches using the exact same branch name, with /sync suffix. For example the branch would be named like username/feature/sync.
The CI automatically fetches submodule <something>/sync branch when building parent <something>/sync branch.
For example if you modify both Unvanquished/ and Unvanquished/daemon/ and the changes in Unvanquished/ requires changes from Unvanquished/daemon/ to build, you need to do a splitted pull request. You would push both your Unvanquished and Dæmon changes to upstream with a branch name like username/feature/sync. And the CI will automatically fetch the username/feature/sync branches of both Unvanquished/ and Unvanquished/daemon/.
Bisecting a tree with submodules
When bisecting the history, you may have to run git submodule update --init --recursive on every step.
While a submodule change that doesn't break compatibility does not strictly requires to be committed, frequent submodule commits makes easier to bisect the tree in the following time.
That's why from time to time we commit the submodules so we can bisect the commits committing the submodules. Such commits, only meant for making bisecting easier, are never done within a pull-requests.
