{{lastupdated_at}} by {{lastupdated_by}}

{{>toc}}

h1. Git workflow

We are using "git":https://git-scm.com/ as version control system for the GammaLib code and "GitLab":https://cta-gitlab.irap.omp.eu/ to manage the git repositories.

Every developer will have an own copy of the GammaLib code in the git repository, hence there is no need (and even no possibility) to push to the gammalib repository. As a developer you will fork the gammalib project, create a feature branch and add some new code (or correct a bug), and issue a pull request so that your change gets included in the trunk. This is identical to the workflow that you will follow when using "GitHub":https://github.com/gammalib/gammalib.

h2. 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):
<pre>
$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com
</pre>In addition, you may add
<pre>
$ git config --global http.sslverify "false"
</pre>so that you have no SSL certificate error when you access Git.


h2. Overview

The figure below illustrates the git workflow that we use for the GammaLib development. Permanent branches are shown as black lines, temporary branches as grey lines. There are three permanent branches in the central git repository:
* the @master@ branch that holds the latest release
* the @devel@ branch that is the trunk on which development progresses
* the @integration@ branch that is used for code integration

A temporary @release@ branch is used for hotfixes and generally for code testing prior to any release. As developer you will fork the GammaLib repository in your private GitLab area and work on temporary @feature@ branches.

| !git-workflow.png! |


h2. Forking the project

As the first step you need to create a fork of the project. Connect to "GitLab":https://cta-gitlab.irap.omp.eu/ with your Redmine user name and password (your user name on Redmine and GitLab is identical), select the "GammaLib":https://cta-gitlab.irap.omp.eu/gammalib/gammalib project and click on "Fork" (highlighted by the red box below):

| !gitlab-fork-step1.jpg! |

This brings you to a screen that invites you to fork (i.e. copy) the project to your user account. Click on your user (highlighted by the red box below):

| !gitlab-fork-step2.jpg! |
| !gitlab-fork-step3.jpg! |

After a short while a fork will be created that now is under your ownership. You can access this fork through the HTTPS protocol at the address @https://cta-gitlab.irap.omp.eu/<user>/gammalib.git@ where @<user>@ needs to be replaced by your user name (your user name on Redmine and GitLab is identical). For the example below, you create a clone by typing in a shell:
<pre>
$ git clone https://cta-gitlab.irap.omp.eu/jknodlseder/gammalib.git
$ git init
</pre> 

We recommend adding the main gammalib repository as a remote repository named @upstream@ so that you can fetch the latest code version before you start a new feature:
<pre>
$ git remote add upstream https://cta-gitlab.irap.omp.eu/gammalib/gammalib.git
</pre>


h2. Modifying or adding code

To work on a feature or to correct a bug you step in the @gammalib@ directory that was created after cloning and you create a new feature branch using
<pre>
$ git pull upstream devel
$ git checkout -b 9101-correct-nasty-bug
</pre>The first command pulled in the latest changes from the main gammalib repository. Note that a branch name should always start with the number of the issue you work on and a short description what you actually are planning to do.

Suppose that there is a bug in the @inst/cta/src/GCTAModelIrfBackground.cpp@ file. After correcting the bug you need to stage the change for commit using
<pre>
$ git add inst/cta/src/GCTAModelIrfBackground.cpp
</pre>and then commit the change using
<pre>
$ git commit -m "Fixed the nasty bug (#9101)"
</pre>where the message in hyphens should be as detailed as possible (the example here is definitely not very good). Please also attach the issue number in the commit message. This allows tracking which issues were in fact fixed by a given commit.

Now you can push your change into the git repository using
<pre>
$ git push origin 9101-correct-nasty-bug
</pre>Note that the @origin@ argument specifies where to push the change (@origin@ means to the same repository where you have cloned from), and the @9101-correct-nasty-bug@ argument gives the name of the branch you want to push.

You can now verify on GitLab that a new branch exists in your project:

| !gitlab-push.jpg! |


h2. Issuing a pull request

After having thoroughly checked your new code, and after having pushed the code into your git repository, you can now issue a pull request so that your change gets merged into the main code base (the so called "trunk"). For this you have to open the relevant issue in "Redmine":https://cta-redmine.irap.omp.eu/projects/gammalib/issues and put the status of the issue to "Pull request":

| !pull-request.jpg! |

In the notes field please indicate where your change is. This means you should provide at least your user name on GitLab and the name of the feature branch. You could also copy/paste the HTTPS URL of your repository.

You should also describe in the notes field 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.


h2. Managing your code

h3. Delete a branch

To delete a branch on GitLab, select the "Branches" tab and click on the wastebasket behind the branch you want to delete:

| !gitlab-delete.jpg! |