Advice : If you are a newcomer to the management of a big software application using git, it might be interesting for you to read first the description of the branching model used by ABINIT and many other software applications.
Let us suppose that you are one of the ABINIT developers …
Every “physical” developer of ABINIT using gitlab has his/her specific user_id (e.g. gonze). Moreover, an additional “virtual” developer, called trunk, is also defined.
On the ABINIT gitlab server, an ABINIT project can be defined, specifically for you, with address git@gitlab.abinit.org:user_id/abinit.git. In order to do this, log on https://gitlab.abinit.org, go to “Explore projects”, find “Trunk / Abinit” (+perhaps select “All”), then click on the “Fork” button. You need to contact Jean-Michel Beuken to have access to the ABINIT gitlab.
In order to start to work locally (not on the ABINIT gitlab server, but on your own machine), you should setup the SSH environment for gitlab, as described in the last section of this document. In particular on some machines you need to have an ssh agent running with your rsa key already available, so that git finds it when it runs ssh.
You have by default a master branch and a develop branch in your repository, but can create or work on other branches, following the philosophy of git. In particular, according to gitflow, this master branch will be of little use for the “physical” developers (including you), as we will see later, while the develop and release-* branches will be quite important for you.
The visibility level of the ABINIT projects of the user_id developers and of the trunk developer is “internal”. The trunk/abinit.git (well, only the master branch) is however mirrored on github.
In order to clone from the gitlab repository to your gitlab repository on your local machine (either for the first time, or in order to restart from a fresh copy of the gitlab repository), the recommended command is :
git clone gitlab:user_id/abinit.git -b develop
where user_id is to be replaced by the adequate name.
[Additional explanation : the normal “clone” command from the gitlab repository to his/her gitlab repository on his/her local machine is :
git clone git@gitlab.abinit.org:user_id/abinit.git
However, with the proper SSH environment, the following “clone” command can be used :
git clone gitlab:user_id/abinit.git
This will clone the master, while the usual working branch is the
develop branch, that can be obtained directly with the above-mentioned command.]
After some modifications, using the git commands (e.g. git add, git commit …), you can push on the gitlab server thanks to :
git push –tags ( double-dash before tags )
In order for the modifications to be merged in the trunk, a merge request has to be issued, as described later.
The same might be done for other branches, created from the local develop one, using the commands :
git branch another_branch
git checkout another_branch
For pushing, the first time, use :
git push -u origin another_branch.
You are able to create your own additional branches, either locally or on gitlab. The name is your own choice.
In the ABINIT+git workflow:
The develop branch in the ABINIT naming scheme corresponds to the development stage. The release-* branches in the ABINIT naming scheme corresponds to release candidates or hotfix branches. It is slightly simpler than the gitflow naming scheme.
In the git philosophy, branches are often created, then merged, then destroyed. The ABINIT developer is encouraged to take advantage of this flexibility. However, many developers work only on one main project, and will already be satisfied by simply using their develop branch.
The developer has to use the git on-demand form on the ABINIT buildbot portal (https://bbportal.abinit.org). The authentification is made with login/password of gitlab.
One important feature has to be taken into account : with git, each commit is characterized by a SHA-1 code (40 hexadecimal characters). The four first characters actually define the commit with 1 combination out of 65536 4-character combinations, while the five first characters define the commit with 1 combination out of 1048576 5-character combinations.
Gitlab knows the repository of the different users, the existing branches, as well as the SHA-1 code of each commit. The three following fields must be defined by the developer for buildbot to know which is the revision of ABINIT to be run:
For a develop branch to be on-track, a specific commit must be contained in the past history of the branch. This specific commit will be tagged in the trunk/develop branch (actually, corresponding to the definition of the start of the version).
For a release-* branch to be on-track, not only a specific commit must be contained in the past history of the branch, but also the commit that starts the next development version cannot be present. Only one among the release-* branches is on-track at any time.
As an example, suppose we were on ABINIT v9.9.3, and want to start preparing a release 9.10.1 (for release) and a new v9.11.0 (for development) :
In complement to the start of a X.Y.Z version for release being tagged as “start-X.Y.Z”, the commit that ends some X.Y.Z version for release will be tagged “X.Y.Z”.
(See the Buildbot Status at https://bbportal.abinit.org/#/status)
The Buildbot Status table show a summary of the recent results obtained by the test farm for active branches. If you want to see all the results, select the “filters” : all + all , then click on the update button. The default selection of bots, that is the “night” set, should be adequate for all merge requests. The selection capabilities of the Buildbot Status table are rather extended, you have to play a bit wit them.
In order for your development to be incorporated, there should be a gitlab “merge request” from your specific user_id to the trunk. For most branches of user_id, the merge request will be to the trunk/develop branch. (See the list of merge requests at https://bbportal.abinit.org/#/mr)
However, when a release-* branch is ready to be merged, the “merge request” should target the corresponding trunk/release-* branch.
The master branch is only used by the trunk. So, never issue a merge request to trunk/master.
You are supposed to merge, inside your branches, specific tagged branches from the trunk user, in order to avoid divergences. These specific tagged branches will be advertised. As mentioned earlier, the presence of such tagged commits allows one to identify whether the branch is on-track, before an automatic testing to be done.
In order to keep your branches user_id/develop or user_id/release-* up to date with those of the trunk virtual user, you should first define git@gitlab.abinit.org:trunk/abinit.git as a remote :
git remote add trunk gitlab:trunk/abinit.git
Then, in order to synchronize, in a first step, issue :
git pull -t trunk develop
git push --tags
then, if the develop branch is to be updated, supposing it is checked out, merge the trunk/develop in your develop :
git merge remotes/trunk/develop
If you have a hotfix, a new branch has to be created. To fix the ideas, let's suppose you want to communicate a bug fix to ABINITv9.8, you have to issue :
git branch release-9.8 start-9.8.0 (this creates the branch release-9.8 from the start-9.8.0 tag) git checkout release-9.8 git merge remotes/trunk/release-9.8 git push -u origin release-9.8 --tags
That's it ! You can now make modifications in your release-9.8, then issue a merge request to the trunk/release-9.8 .
To see which branches are present in your current copy of abinit type: git show-branch -a (documented at https://git-scm.com/docs/git-show-branch). This should also list the remotes (if not add -r). An example output:
* [develop] Merge branch 'develop' of gitlab:trunk/abinit into develop
! [master] Minor modif, to initialize v8.7.3 modified: KNOWN_PROBLEMS
! [origin/HEAD] Minor modif, to initialize v8.7.3 modified: KNOWN_PROBLEMS
! [origin/develop] Merge branch 'develop' of gitlab:trunk/abinit into develop
! [origin/master] Minor modif, to initialize v8.7.3 modified: KNOWN_PROBLEMS
! [trunk/develop] Import inside gitlab develop, the modifications from v8.6.2 to v8.6.3
! [trunk/master] Minor modif, to initialize v8.7.3 modified: KNOWN_PROBLEMS
The syntax is compact but a bit barbaric: the first section gives you the branches which are actually present, with a star for the one currently checked out. The other branches are offset by 1 space.
- - [develop] Merge branch 'develop' of gitlab:trunk/abinit into develop * + + [trunk/develop] Import inside gitlab develop, the modifications from v8.6.2 to v8.6.3
The second section shows commits, and can tell you the relation between the branches. Commits are marked with a + in each column for each branch they are included in, and merges with a -. Note that the master branches are never used, the top commit is a merge of trunk into the current develop, and the second commit is contained in the currently active, the origin/develop (of which it is just a clone), and the trunk/develop branches.
In order to avoid typing your password every time you issue a command that accesses gitlab, you have to introduce your public keys in your profile ( https://gitlab.abinit.org/profile/keys ).
On your local machine, generate a ssh key of RSA type only WITHOUT passphrase :
ssh-keygen -t rsa
and call it id_rsa_gitlab .
Then add a section in the ~/.ssh/config file :
host gitlab Hostname gitlab.abinit.org User git KeepAlive yes IdentityFile ~/.ssh/id_rsa_gitlab
and then, copy the public key id_rsa_gitlab.pub on gitlab.
Now, you can use (on your local machine) the following syntax :
git clone gitlab:user_id/abinit.git
instead of the above-mentioned
git clone git@gitlab.abinit.org:user_id/abinit.git
To be sure the key is proposed each time git calls ssh, you can use ssh-agent:
ssh-agent # this starts the agent, and provides the process id # execute the 3 lines of commands that ssh-agent proposes, e.g. SSH_AUTH_SOCK=/tmp/ssh-ngsERHER3K1HS/agent.15589; export SSH_AUTH_SOCK; SSH_AGENT_PID=15590; export SSH_AGENT_PID; echo Agent pid 15590; ssh add ~/.ssh/id_rsa_gitlab # add the corresponding ssh key for gitlab
For further details, please consult the official documentation <https://gitlab.abinit.org/help/ssh/README.md>