Difference between revisions of "Lazarus Team - Git Workflows"

From Lazarus wiki
Jump to navigationJump to search
(→‎Continuous integration (CI) System: - reflect updates to CI configuration)
Line 61: Line 61:
 
= Continuous integration (CI) System =
 
= Continuous integration (CI) System =
  
On every commit 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.
+
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:
 
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:
Line 76: Line 76:
  
 
# 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.
 
# 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.
# Update Qt5Pas bindings and cache this job's result. This process is triggered automatically when ''lcl/interfaces/qt5/cbindings'' directory contents are changed. 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.
+
# 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:
 
# 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 and stable FPC);
 
#* x86_64-gtk2 bigide (oldstable and stable FPC);
Line 85: Line 85:
 
At the time of writing this section the following jobs for building Lazarus are built automatically on every commit:
 
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-gtk2 bigide (stable FPC);
* x86_64-qt5 bigide (stable FPC);
+
* x86_64-qt5 bigide (oldstable FPC);
* i386-win32 bigide (oldstable FPC).
+
* i386-win32 bigide (stable FPC).
 
All others can be triggered manually via GitLab web interface.
 
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).
 
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).
 
Normally you will see only two stages (1 and 3). Stage 2 is only shown when GitLab thinks that Qt5Pas bindings have to be rebuilt (''lcl/interfaces/qt5/cbindings'' directory contents are changed).
 
  
 
Important notice for Qt5 jobs:
 
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 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:
+
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.
 
# Stop the currently running pipeline if needed.
 
# Press '''Clear runner caches''' button.
 
# Press '''Clear runner caches''' button.

Revision as of 23:42, 17 August 2022

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

or

   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.

Use

   git cherry pick -x

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

".gitattributes" - Adding new file extensions

Warning-icon.png

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

Milestone

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
merge::merge-and-close

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]) 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 and stable FPC);
    • x86_64-qt5 bigide (oldstable and stable FPC);
    • x86_64-win64 bigide (oldstable and stable FPC);
    • i386-win32 bigide (oldstable and stable 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-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).