|Gerrit Code Review - Superprojects subscribed to submodules updates
|Gerrit supports a custom git superproject feature for tracking submodules.
|This feature is useful for automatic updates on superprojects whenever
|a change is merged on tracked submodules. To take advantage of this
|feature, one should add submodule(s) to a local working copy of a
|superproject, edit the created .gitmodules configuration file to
|have a branch field on each submodule section with the value of the
|submodule branch it is subscribing to, commit the changes, push and
|merge the commit.
|When a commit is merged to a project, the commit content is scanned
|to identify if it registers git submodules (if the commit registers
|any gitlinks and .gitmodules file with required info) and if so,
|a new submodule subscription is registered.
|When a new commit of a registered submodule is merged, gerrit
|automatically updates the subscribers to the submodule with a new
|commit having the updated gitlinks.
|Git Submodules Overview
|It is a git feature that allows an external repository to be
|attached inside a repository at a specific path. The objective here
|is to provide a brief overview, further details can be found
|in the official git submodule command documentation.
|Imagine a repository called 'super' and another one called 'a'.
|Also consider 'a' available in a running gerrit instance on "server".
|With this feature, one could attach 'a' inside of 'super' repository
|at path 'a' by executing the following command when being inside
|git submodule add ssh://server/a a
|Still considering the above example, after its execution notice that
|inside the local repository 'super' the 'a' folder is considered a
|gitlink to the external repository 'a'. Also notice a file called
|.gitmodules is created (it is a config file containing the
|subscription of 'a'). To provide the sha-1 each gitlink points to in
|the external repository, one should use the command:
|git submodule status
|In the example provided, if 'a' is updated and 'super' is supposed
|to see the latest sha-1 (considering here 'a' has only the master
|branch), one should then commit the modified gitlink for 'a' in
|the 'super' project. Actually it would not even need to be an
|external update, one could move to 'a' folder (insider 'super'),
|modify its content, commit, then move back to 'super' and
|commit the modified gitlink for 'a'.
|Creating a New Subscription
|Defining the Submodule Branch
|This is required because Submodule subscription is actually the
|subscription of a submodule project and one of its branches for
|a branch of a super project.
|Since it manages subscriptions in the branch scope, we could have
|a scenario having a project called 'super' having a branch 'integration'
|subscribed to a project called 'a' in branch 'integration', and also
|having the same 'super' project but in branch 'dev' subscribed to the 'a'
|project in a branch called 'local-dev'.
|After adding the git submodule to a super project, one should edit
|the .gitmodules file to add a branch field to each submodule
|section which is supposed to be subscribed.
|The branch field is not filled by the git submodule command. Its value
|should indicate the branch of a submodule project that when updated
|will trigger automatic update of its registered gitlink.
|The branch value could be '.' if the submodule project branch
|has the same name as the destination branch of the commit having
|The branch field of a submodule section is a custom git submodule
|feature for gerrit use. One should always be sure to fill it in
|editing .gitmodules file after adding submodules to a super project,
|if it is the intention to make use of the gerrit feature introduced here.
|Any git submodules which are added and not have the branch field
|available in the .gitmodules file will not be subscribed by gerrit
|to automatically update the superproject.
|Detecting and Subscribing Submodules
|Whenever a commit is merged to a project, its content is scanned
|to identify if it registers any submodules (if the commit contains new
|gitlinks and a .gitmodules file with all required info) and if so,
|a new submodule subscription is registered.
|Automatic Update of Superprojects
|After a superproject is subscribed to a submodule, it is not
|required to push/merge commits to this superproject to update the
|gitlink to the submodule.
|Whenever a commit is merged in a submodule, its subscribed superproject
|Imagine a superproject called 'super' having a branch called 'dev'
|having subscribed to a submodule 'a' on a branch 'dev-of-a'. When a commit
|is merged in branch 'dev-of-a' of 'a' project, gerrit automatically
|creates a new commit on branch 'dev' of 'super' updating the gitlink
|to point to the just merged commit.
|Canonical Web Url
|Gerrit will automatically update only the superprojects that added
|the submodules of urls of the running server (the one described in
|the canonical web url value in gerrit configuration file).
|The Gerrit instance administrator group should always certify to
|provide the canonical web url value in its configuration file. Users
|should certify to use the url value of the running gerrit instance to
|If one has added a submodule subscription and drops it, it is
|required to merge a commit updating the subscribed super
|project/branch to remove the gitlink and the submodule section
|of the .gitmodules file.
|Part of link:index.html[Gerrit Code Review]