[Build] Use latest commit of branch specified in .gitmodules file

[HannesWell]

This simplifies trying out changes in a submodule and their effect on the entire Eclipse-SDK in advance. Instead of always fetching the latest commit from the master branch of the specified remote, fetch the latest commit of the branch specified in .gitmodules from each submodule's remote (also specified in .gitmodules).

In order to try out a change with the entire Eclipse-SDK, now one just has to update the affected submodules in the .gitmodules file to point to the git-repository and the branch providing the change(s).

Before, one either had to push changes to the 'master' branch of the alternative repository providing a change or had to disable the fetch in this Jenkins pipeline and record the change's commit in this aggregator repository along with changing the of the remote in .gitmodules. Of course all of this had to be known.

Additionally add a comment explaining how to archive the just built product with a Jenkins build.

@HeikoKlare IIRC you recently had difficulties to try out a change from a fork in the Eclipse-SDK. This should make it much simpler.

[laeubi]

I always though this was by intention... Would it not mean that we now can't verify changes outside before updating submodule manually?

[HeikoKlare]

If I understand correctly, this change should basically do nothing but making it easier to consistently modify the submodules (i.e., remote and maybe branch) for testing, doesn't it? The problem was that Jenkins builds used master branch in a hard-coded way while you can now just change the branch to be taken in the .gitmodules, right?

But how does that relate to the version information of the submodules themselves (i.e., the references commit or tag id)? Will the commit/tag be taken unless you do a git submodule update --remote?

[HannesWell]

If I understand correctly, this change should basically do nothing but making it easier to consistently modify the submodules (i.e., remote and maybe branch) for testing, doesn't it? The problem was that Jenkins builds used master branch in a hard-coded way while you can now just change the branch to be taken in the .gitmodules, right?

That's all correct.
By default Jenkins checks out the submodules at the commit-Ids recorded in this aggregator repository (like if you performed git submodule update or Update submodule on the Submodules element of a repository in EGit's Git Repositories view).

To quote from the git submodule update documentation:

Update the registered submodules to match what the superproject expects by cloning missing submodules, fetching missing commits in submodules and updating the working tree of the submodules. The "updating" can be done in several ways [...]. If neither is given, a checkout is performed.

checkout
    the commit recorded in the superproject will be checked out in the submodule on a detached HEAD.

In the current state (before this change) the Jenkins pipeline just always fetched the latest commit of the master branch at the specified remote of each submodule. This PR changes that to fetch the latest commit of the branch specified in .gitmodules at the specified remote of the respective submodule. By default that branch is the master branch, even if no branch is specified in the .gitmodules file. Nevertheless I specified the default explicitly to make it simpler to change the branch as well, as PRs are usually not created at the master branch of a fork.

To make a long story short. For the default case, i.e. with outh modifications everything stays (or should stay) as it is now, it just becomes simpler to change a submodule to a different repo and branch.

[HannesWell]

My final testing revealed that actually the Jenkins multibranch-pipeline job is already configured to have exactly the desired behavior:

I assume that was configured after the stage was introduced. So we can actually just remove the corresponding stage.