Lazarus Team - Git Workflows
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
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
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.
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-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:
- Update our Docker image (see above). This process can be triggered manually in CI/CD->Pipelines page by running update-build-env job of the first manual stage of the most recent pipeline belonging to main branch (rebuilding process takes ~35 min). It should be run in the following cases:
- When there is a desire to simply update FPC fixes and main snapshots. It is safe if FPC versions haven't changed in the meantime (in rare cases rebuilding process (FPC snapshots compilation) may fail, re-run the job in this case). It is enough to just run the job (no variables need to be defined), the image will be updated automatically and will include FPC snapshots at the time of rebuilding of image.
- When Dockerfile.buildenv and/or FPC version constants in .gitlab-ci.yml file have been changed. Do with care!
- 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.
- 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 run 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:
- Stop the currently running pipeline if needed.
- Press Clear runner caches button.
- Press Run pipeline button (you will be asked about defining variables, just skip this step (we don't use them) and confirm running pipeline).