Gitlab user guide

basics

Git is a distributed version control system (VCS) software. You can learn from the official book.

Gitlab is an git server server to support collaboration git development. In addition to a standard git server, it provides functions to simplify collaboration, such as issues, merge requests(MR). See the link for details about gitlab.

git settings

You should at lease setup your name and email with git config.

In addition, to maximize the effiency and avoid massing up, the following should be set (at least for your HERDOS clone. you may skip the --global parameter if you don¡¯t want apply for other git clones).

git config --global pull.rebase true
git config --global push.default simple

Developing, branching and merging strategy

Planning

  • When users discover an issue in the software, or propose new requirements, they are encoraged to create an issue on the issue tracker of the corresponding repository and specify the relevant sub-system convener as the assignee.

  • The relevant sub-system convener should split the issue, reassigns the assignees, and distribute tasks according to the issues raised.

  • Users who raised the issue need to discuss with the assignee in the issue tracker, track the progress of the issue, and provide feedback after the development is submitted. The relevant sub-system convener needs to follow up on the issue¡¯s progress in a timely manner. If the requirement is met or the issue is solved, or the group decides that the issue cannot be solved, the relevant system convener decides whether the issue should be closed.

  • Branch name related to the issue should start with the issue number (e.g. 53-flexscan-geosvc).

Development

  • The master branch does not accept direct commits. Two development models are encouraged: the forking-mergeRequest and branching-mergeRequest.

  • The forking-mergeRequest model refers to developing on a personal repository forked from the main repository, and then merging it back to the main repository via a merge request (MR) once it is mature.

  • The branching-mergeRequest refers to creating a branch on the main repository, developing on that branch, and then merging it back to the master branch via an MR once it is mature.

  • The branching-mergeRequest model is encouraged, and should always be considered as the first choice, since the branch in the main repository is visible to the collaboration.

  • The forking-mergeRequest model is suitable for private development, or development carried out by a small sub-group (such as an independent reconstruction algorithm). It is not suitable for long-term development of the core components (software components that have big impact on other parts, such as the framework, EDM etc.), since the private repository is usually not visible to the whole collaboration.

  • Commits from forked repositories can not be directly merged to the master branch in the main repository. This is mainly because the CI runner is usually not available in forked repositories. Commits from forked repositories should firstly be merged in another branch in the main repository. And once it is reviewed, and the CI is passed, it could be merged to the master branch.

  • Commit messages should be written in English. The commit messages should concisely and completely describe the changes.

  • Coding conversion should be followed. Please refer to the coding conversion documentation.

  • Newly developed features must provide unit test. The unit test should be added to the CI system. The relevant documentation needs to be updated at the same time. The system convenor should check whether theses requirements are met.

  • For larger or more extensive changes, a corresponding issue needs to be created, and the primary developer of the related development should be assigned as the assignee.

Merging

  • Before merging any code into the master branch, you should: 1) resolve all conflicts and all discussion threads in the relavant issues; 2) pass all CI tests; 3) obtain review and approval from the relevant system convener.

  • If there are conflics between branches or repositories, they should be resolved via the rebase approach.

  • To ensure a clean history on the master branch of the main repository, multiple commits with similar or related functionality should be squashed (please check the squash-commits check-box before clicking the merge button). The fastforward method is encouraged to avoid merge commits.

  • The source branch could be deleted after merging (please check the delete checkbox before merging).

  • Urgent bug fixes submitted to the master branch that are required by other branches or forked repositories could be merged according to specific requirements.

  • Each MR requires the assignment of an assignee and a reviewer. The assignee is typically the relevant developer, while the reviewer is typically a relevant system convenor. In principle, the assignee and reviewer cannot be the same person.

  • Newly developed features and bugfixes should be merged as soon as possible. If the development needs to be frozen, the relavant system convenor decides whether to do so.