Working with Git

This guide is meant to help you set up an account in Gitlab and use the hosting service provided by Strategy Object via GitLab to host your projects.

SO Hosting Service via GitLab

Strategy Object hosts a dedicated space on GitLab for joint private projects with client countries: https://gitlab.com/strategyobject/countries.

GitLab is a web-based service for hosting software projects and supporting a secure and collaborative work on them. Based on Git, it offers distributed version control and source code management.

GitLab accounts of the developers involved have to be added with access to that project for submitting, reviewing and approving changes.

It is essential that all the changes to that project are submitted via merge requests and approved by all member developers.

GitLab Project Details

Your GitLab project will be set up in the following way:

Your modules will be uploaded in a private project space provided by Strategy Object and hosted on GitLab.
A team of developers to access and work on that project will be created.
The project will have two main branches:
1. master - holds the current production version;
2. devel - accepts new features and bug fixes via merge requests.
The project will be created as Protected so all the changes would have to be submitted explicitly through merge requests.

Account Settings

There are several ways to connect to and interact with GitLab repositories.

The sections below cover the most common account settings in GitLab.

SSH Keys

In order to be able to work with GitLab it is recommended to connect to GitLab using SSH keys.
Follow the steps below to add your SSH key.

Go to your account settings in GitLab by pressing the icon of your user account (in the top right corner) and selecting the Preferences option from the drop-down menu, that will appear:
Then on the menu in the left side of the browser, select the SSH Keys option:
A page with a form to add SSH keys will appear. Enter the public key’s value in the Key field and press the blue Add key button.

Access Tokens

For interaction with registries you might also need an access token. Follow the steps below to generate one.

Go to your account settings in GitLab by pressing the icon of your user account (in the top right corner) and selecting the Preferences option from the drop-down menu, that will appear:
Then on the menu, in the left side of the browser, select the Access Tokens option:
A page with a form for generating access tokens will appear. Give this token a name that will provide a hint for its purpose; fill it in the Token name field. Check the last two options in the Select scope list to have read and write access to the repository. Then click the blue Create personal access token button.

A token will be generated and you can copy its value and use it for logging into GitLab via a terminal.

Working with Projects

Overview

Each time someone wants to make any changes to the devel branch, they will have to first clone/pull changes from the devel branch and then make a checkout into a new branch, naming it following this convention:

If a new feature is being added: feature/changes-made;
If a bug is being fixed: bugfix/what-was-fixed.

The branch names changes-made and what-was-fixed could actually be made up of the task name or number in the respective task manager used for your project.

Then, upon submitting the branch with the changes, the developer will get a web link. They have to open this link in a web-browser in order to access the GitLab’s web interface to create a merge request and add reviewers and approvers.

Afterwards the developers added as reviewers and approvers will review the submitted changes and the code. They will either make comments and remarks for improvement or approve the merge of the branch with the changes to the devel branch. After approval the developer should merge their branch with changes. This action can also be performed using the GitLab’s web interface.

Clone a Project

All commands below are executed in a Terminal.

Before submitting anything to GitLab, you will have to clone the project locally. The <country> in the examples below should be replaced by your country code or name for your project hosting service, provided to you by Strategy Object:
- via SSH if you have set up to use a personal key in your GitLab account:

git clone git@gitlab.com:strategyobject/countries/<country>.git

- via HTTPS using username and password for your GitLab account:

git clone https://gitlab.com/strategyobject/countries/<country>.git

The project will be cloned into a folder named <country> into the location where you have opened the terminal and executed the git command above.

The easiest way to find the proper clone link for your project is to click the blue Clone button in the top right section of the project file list.

Common Workflow

All changes are first made to the devel branch. They are made using so called merge requests (MR), and not via a direct push to the devel branch.

To create a merge request, first you have to create a branch from the devel branch. Give it a name that describes the changes that you are going to make and submit to the project.

After you make the necessary changes, you can submit them in your branch and create a merge request for them to be reviewed, approved and merged with the devel branch.

Follow the steps below to create a merge request in GitLab using terminal commands. You can also get acquainted with the Git options and tools provided by the IDE that you are using for development.

1. Switch to the devel branch:

git checkout devel

2. Create a branch based on the devel branch before making any changes:

git checkout -b my-changes-branch

3. Start working on your task. Make all the necessary changes, which might be: add, edit or delete files of the project. When you complete your task, check what is tracked as changed:

git status

4. If all your changes are listed by the above command, and no extra unexpected files/folders have been accidentally added, then add (stage) them for committing:

git add .

5 Add a commit message describing what has been changed:

git commit -m "Your changes description goes here."

6. Push your branch with the changes to GitLab:

git push origin my-changes-branch

After the completion of the push process, you will see a Web link in the terminal. It will be structured similar to this link: https://gitlab.com/strategyobject/countries/country/merge_requests/new?merge_request%5Bdevel%5D=my-changes-branch. Copy and open that link a Web browser and add viewers and approvers using the GitLab's web interface. After receiving approval of the changes, you have to merge the request with the devel branch.

Merge requests to the master branch are also possible, though not common, upon the need of the so called hot fixes to a recently released version.

For more information please refer to the GitLab Documentation.

Tags and Releases

Tags give you the option to mark specific points in project’s timeline as important.

In GitLab you can use both lightweight and annotated tags.

Lightweight tags are used for marking milestones of the project development. The example below will add a lightweight tag to the last commit made to the project:

git tag <tag-name>

Annotated tags are used for marking releases. The example below will add an annotated tag to a specific commit:

git tag -a <tag-name> -m "<annotation>" [commit]

Use the git log command to get the exact commit hash which you want to add a tag to.

Releases in GitLab are kind of snapshots of significant stable states of your project. Use semantic versioning in tags to prepare the project for a release.

When a project reaches a stable state in the devel branch, a release branch is created out of it, which is then tagged with the semantic version number and merged with the master branch.

It is also recommended to include release notes to the new version describing all the changes made. You can write those in the tag’s annotation message.

Deleting a tag associated with a release will result in also deleting the respective release.

For more information please refer to the GitLab Documentation.