GitLab best practice: Difference between revisions
m →Roles: Adding picture |
No edit summary |
||
| Line 1: | Line 1: | ||
[[Main Page]] -> [[Documentation]] -> [[ | [[Main Page]] -> [[Documentation]] -> [[GitLab best practice]] | ||
This page is summarizing guidelines how to use Gitlab within the project. Some general information how to work with GitLab can be found under the following | This page is summarizing guidelines how to use Gitlab within the project. Some general information how to work with GitLab can be found under the following | ||
Revision as of 17:08, 9 February 2021
Main Page -> Documentation -> GitLab best practice
This page is summarizing guidelines how to use Gitlab within the project. Some general information how to work with GitLab can be found under the following external links:
GitLab is a web service for git, the stupid content tracker (according to the man page). Git implements distributed repositories, git itself does not even make an assumption about a master repository. It is however good to have such a master repository and dedicated strategy how to contribute to it. This is, where GitLab enters the scene. The web service is hosting remote repositories and implements procedures for synchronization and content merging.
In the pCT project we have master repositories for different sub-projects. Check the repositories in the GitLab pCT group.
In this description, we are using the pct-online repository as an example.
Terminology
When working with git/Gitlab, you will meet a few terms:
- branch: the tip of a sequence of commits, branches share a common history and develop independently from one point in the history
- merge: two branches are brought together and the result commited with a new commit
- rebase: the history of a branch is applied to another branch resulting into a new history containing the commits of both branches
- fork: repository copy in a other user space of Gitlab server system
- clone: local working copy on a machine
Default branch structure
The main repository has the following branches:
- production: the latest production code, in this branch we have release tags
- master: the latest stable release
- dev: the development branch
Note that we are currently only using the ```dev``` branch. The production and master branches will be populated while we are progressing with the development.
In addition to those main branches there can be feature branches where development happens detached from the main branches. A feature branch is based on the dev branch and has a limited lifetime.
Roles
There are two very different use cases, the
- User role: A user wants to download the code, compile it and use it.
- Developer role: A developer contributes to the development.
From the GitLab web interface pct-online, an archive can be downloaded.
See further down for instructions how to create a repository clone.
The developer fork
The developer fork is the main feature in Gitlabs/Githubs concept of distributed development, code sharing and code review.
Synchronizing developer fork with main repository
This should be done regularly!
There is unfortunately no simple synchronization feature for forks within Gitlab (from Gitlab Enterprise Edition 8.2 repository mirroring is provided). Synchronization is done in the local clone.
- Fetch branch from the master repository
git fetch https://gitlab.uib.no/pct/wpn.git dev
- Rebase local branch
git rebase FETCH_HEAD dev
- Push to fork
git push origin dev
Git commits
Log message format
Handling merge requests
Git allows for two merging strategies, the normal and fast-forward (ff) merging. The normal merging adds a merge commit. This adds additional information, when something has been merged. In contrast to that, the latter requires to synchronize the branch to be merged via rebasing, and does not need a merge commit. This results in a linear commit history (not necessarily in time). Whether to use the one or the other depends on the specific case and taste. Many people prefer a linear commit history. As a rule of thumb one can say:
- a relatively small and timely update should be done via ff merge
- big developments outside of the main development tree should be merged with merge commits. This allows also for detailed commit messages.
Automatic merges
Gitlab offers the possibility to initiate the merge of a Merge Request (MR) directly from the Web interface. This is very easy and straight forward, however in the Gitlab Community Edition provided by UiB IT, the normal merge procedure is used. As a consequence, every Gitlab Merge Request initiated from the Web interface will include a merge commit.
Fast-forward merges
Fast-forward merges do in contrast to normal git (and Gitlab) merges not produce a separate merge commit. Gitlab Enterprise Edition offers the feature to use fast-forward merges directly from the Gitlab Web interface. UiB IT is providing Gitlab Community Edition, so we do not have this convenient feature right away.
Why fast-forward merges?
Many people consider a linear commit history as an advantage, i.e. not to have merge commits for every merge. A fast-forward merge can be done if only the branch to be merged has additional commits on top of the common commit history. The merge simply means to forward the tip of the target branch.
Workflow
As Gitlab does not provide the functionality, the merge needs to be done outside Gitlab in a local clone from the master repository.
In the workflow below
- adjust the project name wpn
- adjust the user
- adjust the branch name
- you can skip the cloning if you have a already a clone
Workflow for merging the dev brach from a user fork
- Make a local clone from the master repository
git clone https://gitlab.uib.no/pct/wpn.git
git checkout dev
- or update an existing clone
git checkout dev
git pull --ff-only origin dev
- Fetch branch dev from user fork
git fetch https://gitlab.uib.no/user/wpn.git dev
- Merge alias FETCH_HEAD
git merge --ff-only FETCH_HEAD
- Push the update to the master repository
git push origin dev
Gitlab will automatically recognize that the merge request was merged manually and will close it.
