Using Git and GitLab¶
Every developer will create a user in GitLab and have an own copy (a so called fork) of the ctools code in his/her user space. There is hence no need or possibility to push to the main ctools repository. Once you forked from the ctools repository, you can create feature branches and add some new code (or correct a bug), and issue a pull request so that your change gets included in the trunk. Note that we do not use GitLab’s pull request feature for the moment, as all issues are tracked on our Redmine system, but this may change in the future. Our Git workflow is identical to the one you typically use on GitHub. You may in fact also use GitHub for your code developments, as the ctools source code is mirrored to GitHub in a read only repository.
Before you start¶
Make sure you configured your Git using your user name and e-mail address (you only need to do this once on your machine):
$ git config --global user.name "John Doe" $ git config --global user.email firstname.lastname@example.org
In addition, you may need to add
$ git config --global http.sslverify "false"
so that you have no SSL certificate error when you access the repository.
The figure below illustrates the Git workflow that we use for the ctools development. Permanent branches are shown as black lines, temporary branches as grey lines. The yellow area is the ctools repository, the light blue area is your forked user space. There are three permanent branches in the ctools repository:
masterbranch that holds the latest release
develbranch that is the trunk on which development progresses
integrationbranch that is used for code integration
release branch is used for hotfixes and generally for code
testing prior to any release.
As developer you will work in your user space and work on temporary
Forking the project¶
As the first step you need to create a fork of the project in your user
Connect to GitLab
using your Redmine user name and password (if you have not yet an
Redmine then go
ahead and create one).
Select the ctools
project and click on
This brings you to a screen that invites you to fork the project into your user space. Click on your user.
After a short while a fork will be created that now is under your ownership.
Now you can clone this fork using
$ git clone https://cta-gitlab.irap.omp.eu/[user]/ctools.git
$ git remote add upstream https://cta-gitlab.irap.omp.eu/ctools/ctools.git
You can then type
$ git pull upstream devel
to pull in changes from the
devel branch of ctools in your
Modifying or adding code¶
To work on a new feature or to correct a bug you should always create a new branch. You do this by typing
$ git checkout devel $ git pull upstream devel $ git checkout -b 5783-correct-event-selection
which makes sure that you are on your
devel branch, then pulls in changes
from the ctools repository, and finally creates the
New branches should always start with an issue number, followed by
a meaningful name that indicates what the branch is good for (use hyphens
to separate words).
You can find the relevant issue number using the
Redmine issue tracker.
Suppose that your goal is to correct a bug in the event selection in
You would then probably modify the
ctselect.cpp file that is found in the
Once you have verified that the bug is correct you should commit your changes.
First stage the files you want to commit:
$ git add src/ctselect/ctselect.cpp
and then commit your change:
$ git commit -m "Corrected event selection in ctselect (#5783) > > The event selection in ctselect was not done correctly in case > that no time intervals are specified. This is fixed now."
where the message in quotes should be comprised of a single line subject that describes what was changed, and a message body that describes why the change was made. Subject line and message body should be separated by a blank line (see How to Write a Git Commit Message).
To make the changes available to other users, and specifically to allow their merging into the ctools repository, you need to push you local changes into your GitLab’s repository. You do this by typing
$ git push origin 5783-correct-event-selection
Note that the
origin argument specifies that you want to push your
changes into the same repository from which you cloned the code.
Creating a pull request¶
Once the code is pushed into your repository you can create a request that
your code should be merged into the ctools repository.
For this you have to open the relevant issue in the
Redmine issue tracker
and put the status of the issue to
You should indiciate in the notes in which repository and on which branch your change is. You should also describe the changes or addition you made to the code. Explain what you have done. Say if there is anything you’d like particular attention for - like a complicated change or some code you are not happy with. If you don’t think your request is ready to be merged, just say so in your pull request message. This is still a good way of getting some preliminary code review.