Lazarus Team - Git Workflows

From Lazarus wiki
Jump to navigationJump to search

This page contains workflows for Lazarus team members, when working with GIT.

git pull --rebase

Commits made by team members should have a linear history

If you have local commits to push, and the remote branch has new commits too, then use rebase. Do not create any merge commits.

   git pull --rebase


   git rebase

Merge Requests / Pull Requests

Merge requests should be included by creating a merge commit

   git merge merge-request/foo

Cherry picking / Merging

Do not "squash" commits when cherry picking.

If commits are squashed, then "git cherry" wont work.


   git cherry pick -x

The "-x" adds "cherry picked from commit"

".gitattributes" - Adding new file extensions


Warning: Adding new extensions can have unwanted side effects on existing file.

If you add files with an new extension (not yet covered by .gitattributes) then it is best to add that extension (or the concrete file)

Files not covered by .gitattributes will be left to git figuring out on its own, if they are text. Since this affects line endings, it is best to tell git, what we want the file to be.

After editing .gitattributes you must run (before committing):

   git add --renormalize .

Then check git status which files were affected.

Issue Tracker


When closing an issue, ensure to set the correct milestone.

If the issues is (or will be) merged to a fixes branch, set the milestone for the fixes release. (If the merge later fails, the milestone must be amended).

If you do not merge (cherry pick) yourself:

  • leave the issue open
  • Set the fixes milestone
  • add the label

Continuous integration (CI) System

On every commit and every update to merge requests continuous integration (CI) system creates a pipeline, which builds Lazarus for several platforms/widgetsets. If the build fails, it notifies the creator of commit which caused the failure.

The building process happens in a virtual machine (Docker container), which loads an operating system image. Our image is based on Debian 11 x86_64 and at the time of writing this section contains:

  • GTK2, GTK3, Qt5 libraries;
  • FPC (versions 3.2.0 [oldstable], 3.2.2 [stable], 3.2.3 [fixes], 3.3.1 [main]) for the following targets:
    • x86_64-linux;
    • x86_64-win64 (cross-compiler);
    • i386-win32 (cross-compiler).

Docker image configuration is defined in Dockerfile.buildenv file, and pipeline configuration is defined in .gitlab-ci.yml (both files are located in Lazarus root directory).

At the time of writing this section our pipeline consists of three stages:

  1. Update our Docker image (see above). This process is triggered manually and should be only run when Dockerfile.buildenv and/or FPC version constants in .gitlab-ci.yml file have been changed.
  2. Update Qt5Pas bindings and cache this job's result. Its results are required for subsequent building of Lazarus with Qt5 widgetset. This is needed because building Qt5 bindings takes a long time (~20 min) and they are rarely changed.
  3. Build Lazarus for various widgetsets/platforms. At the time of writing this section the following jobs for building Lazarus are defined:
    • x86_64-gtk2 bigide (oldstable, stable, fixes, main FPC);
    • x86_64-gtk3 bigide (oldstable, stable FPC);
    • x86_64-qt5 bigide (oldstable, stable FPC);
    • x86_64-win64 bigide (oldstable, stable FPC);
    • i386-win32 bigide (oldstable, stable, fixes, main FPC).

At the time of writing this section the following jobs for building Lazarus are built automatically on every commit:

  • x86_64-gtk2 bigide (stable FPC);
  • x86_64-gtk3 bigide (stable FPC);
  • x86_64-qt5 bigide (oldstable FPC);
  • i386-win32 bigide (stable FPC).

All others can be triggered manually via GitLab web interface.

In GitLab web interface you can notice CI/CD menu item at the left. By clicking CI/CD->Pipelines you will get to pipelines list, where you can see build status for each commit. By clicking circles in the Stages column you will get to submenus which will show status of all jobs and will allow to run/rerun them manually (by clicking at play/retry button) and to look at job's log (by clicking at job's name).

Important notice for Qt5 jobs:

They use cached results from stage 2. In absolute majority of the builds this should not cause any problems. But still if stage 2 does not pass or if you get Qt5 widgetset build failure related to Qt5Pas version mismatch or missing cache, make sure to go to the Pipelines page and do the following:

  1. Stop the currently running pipeline if needed.
  2. Press Clear runner caches button.
  3. Press Run pipeline button (you will be asked about defining variables, just skip this step (we don't use them) and confirm running pipeline).