Working with GitLab

Working with GitLab#

GitLab is the online platform used to host the POLARIS source code and it offers some tools for development that we want to make the most of.

Issues#

In the issues tab of GitLab you can view and create Issues, where developers can note and discuss changes that need to be made to the code.

A branch can be created from the Issues page, and related Issues and Merge Requests can also be linked. Issues can then be closed when resolved, and are archived (and possibly revived if they come back!)

  • https://docs.gitlab.com/ee/user/project/issues/

Merge Requests#

The Merge Requests tab on GitLab keeps track of attempts to merge one branch into another - we HIGHLY recommend using this tool for almost all merges done in POLARIS development (the exception being to merge master into your branch occasionally to keep it up to date).

You can create a merge request as soon as you create a branch for your issue, and mark it [WIP] until it is no longer a work in progress.

Most merge requests are attempts to merge code into master, but you can use the tool for merges into any branch. It is recommended to merge related branches into one another before bringing them into master.

  • https://docs.gitlab.com/ee/user/project/merge_requests/

CI/CD#

When you create a commit and send it to the remote repository, a few processes are run on it. For POLARIS, there are building the code and running simple tests, as well as runner a linter (code formatter). If either of these fails, merge requests will be denied, so pay attention.

Note that these tests are run on Linux using GCC, instead of the Visual Studio compiler, and therefore your changes may not build even if they work locally. Investigate the issue and see what is causing the error - most likely it is a misuse (or lack of) typename and template keywords in the code.

The results of the CI/CD pipeline are visible next to commits, branches, and merge requests. It will be either a green checkmark (success), red X (failure), or blue clock (pipeline still running, wait a minute).

pipeline_failed

If you click the results of the pipeline you will be brought to the pipeline menu, where you will see more info, including which job failed (for us, these are “build” and “lint”).

pipeline_menu

Then you can click the results of these jobs to have the full info on the job.

pipeline_results

Linting Locally#

There is a file in our repo, clang-format-11.exe, that allows Visual Studio to format the code you write locally. To enable it, go here in Visual Studio:

Tools > Text Editor > C/C++ > Code Style > Formatting

And enable the option to use custom clang-format.exe file. You can find our file here:

polaris-linux\bin\clang-format\clang-format-11.exe

This section also includes a number of options for when you want the formatter to kick in. You should play around with this to find out what you like, since formatting too often may be annoying and slow down your work.

There are also extensions you can install that handle this more gracefully, such as “Format on Save for VS2022.” With this, you can right click Projects in the Solution Explorer, click “Format(FormatOnSave) in Project,” and every file that needs to be formatted will be. It may ask if you want to overwrite an existing file, which is fine.