Lazarus Team - Git Workflows: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		This page contains workflows for Lazarus team members, when working with GIT.
2	2
3	3		# git pull --rebase
4	4
5	5		Commits made by team members should have a linear history
6	6
7	7		If you have local commits to push, and the remote branch has new commits too, then use rebase. Do not create any merge commits.
8	8
9		-	~~` git pull --rebase`~~
	9	+	```text
	10	+	git pull --rebase
	11	+	```
10	12
11	13		or
12	14
13		-	~~` git rebase`~~
	15	+	```text
	16	+	git rebase
	17	+	```
14	18
15	19		------------------------------------------------------------------------
16	20
17	21		See also [[SVN to GIT Cheatsheet\|SVN_to_GIT_Cheatsheet#Recommended]]
18	22
19	23		# Merge Requests / Pull Requests
20	24
21	25		Merge requests should be included by creating a merge commit
22	26
23		-	~~` git merge merge-request/foo`~~
	27	+	```text
	28	+	git merge merge-request/foo
	29	+	```
24	30
25	31		> Note: To pull merger request to your local git: <https://docs.gitlab.com/ee/user/project/merge_requests/reviews/#checkout-locally-by-modifying-gitconfig-for-a-given-repository>
26	32
27	33		----
28	34
29	35		Merge-requests can be (optionally / recommended, if the fork-point is way back) rebased first. Within the gitlab merge-request website, this can be done adding a comment
30	36
31		-	~~` /rebase`~~
	37	+	```text
	38	+	/rebase
	39	+	```
32	40
33	41		# Cherry picking / Merging
34	42
35	43		Do not "squash" commits when cherry picking.
36	44
37	45		If commits are squashed, then ["git cherry"](https://git-scm.com/docs/git-cherry) wont work.
38	46
39	47		Use
40	48
41		-	~~` git cherry pick -x`~~
	49	+	```text
	50	+	git cherry pick -x
	51	+	```
42	52
43	53		The "-x" adds "cherry picked from commit"
44	54
45	55		# ".gitattributes" - Adding new file extensions
46	56
47	57		> Warning: Adding new extensions can have unwanted side effects on existing file.
48	58
49	59		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)
50	60
51	61		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.
52	62
53	63		After editing .gitattributes you must run (before committing):
54	64
55		-	~~` git add --renormalize .`~~
	65	+	```text
	66	+	git add --renormalize .
	67	+	```
56	68
57	69		Then check git status which files were affected.
58	70
59	71		# Issue Tracker
60	72
61	73		## Milestone
62	74
63	75		When closing an issue, ensure to set the correct milestone.
64	76
65	77		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).
66	78
67	79		If you do not merge (cherry pick) yourself:
68	80
69	81		- leave the issue open
70	82		- Set the fixes milestone
71	83		- add the label
72	84
73	85
74	86
75	87		merge::merge-and-close
76	88
77	89		# Continuous integration (CI) System
78	90
79	91		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.
80	92
81	93		The building process happens in a virtual machine (Docker container), which loads an operating system image. Our image is based on Debian 12 x86_64 and at the time of writing this section contains:
82	94
83	95		- GTK2, GTK3, Qt5, Qt6 libraries;
84	96		- FPC (versions 3.2.0 \[oldstable\], 3.2.2 \[stable\], 3.2.3 \[fixes\], 3.3.1 \[main\]) for the following targets:
85	97		- x86_64-linux;
86	98		- x86_64-win64 (cross-compiler);
87	99		- i386-win32 (cross-compiler);
88	100		- Pas2JS compiler (Git snapshot, compiled with FPC main compiler/sources).
89	101
90	102		Docker image configuration is defined in buildenv.Dockerfile file, and pipeline configuration is defined in .gitlab-ci.yml (both files are located in Lazarus root directory).
91	103
92	104		At the time of writing this section our pipeline consists of four stages:
93	105
94	106		1. Update our Docker image (see above). This process can be triggered manually in Build-\>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 ~23 min). It should be run in the following cases:
95	107		1. 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.
96	108		2. When buildenv.Dockerfile and/or FPC version constants in .gitlab-ci.yml file have been changed. Do with care!
97	109		2. Clear Qt5Pas/Qt6Pas bindings caches if (and only if) any file in bindings is changed. Reasons to keep this stage separate from updating Qt5Pas/Qt6Pas bindings:
98	110		1. Cache actually contains all files from bindings directory (both source and object ones) and is extracted after checkout, so it overwrites checked out sources, and thus prevents correct cache update if not cleared appropriately.
99	111		2. Sources should be kept in cache, as removing them will cause bindings to be always recompiled (both in bindings and IDE compile jobs). It takes long time and thus undesirable.
100	112		3. Simply doing full cache rebuild if any file in bindings is changed is not enough as this job will not be triggered e. g. for a new merge request (if it does not modify bindings) and will cause IDE compile jobs for it to fail. GitLab CI currently does not support conditions for triggering a job if a cache is missing.
101	113		3. Update Qt5Pas/Qt6Pas bindings and cache results of these jobs. They are required for subsequent building of Lazarus with Qt5 and Qt6 widgetsets. This is needed because building both Qt5 and Qt6 bindings takes a long time (~25 min) and they are rarely changed.
102	114		4. Build Lazarus for various widgetsets/platforms. The following jobs for building Lazarus are defined:
103	115		- x86_64-gtk2 bigide (oldstable, stable, fixes, main FPC);
104	116		- x86_64-gtk3 bigide (oldstable, stable FPC);
105	117		- x86_64-qt5 bigide (oldstable, stable FPC);
106	118		- x86_64-qt6 bigide (oldstable, stable FPC);
107	119		- x86_64-win64 bigide (oldstable, stable FPC);
108	120		- i386-win32 bigide (oldstable, stable, fixes, main FPC);
109	121		- Documentation (stable, fixes, main FPDoc);
110	122		- Tests for Codetools (main FPC).
111	123
112	124		At the time of writing this section the following jobs for building Lazarus run automatically on every commit:
113	125
114	126		- x86_64-gtk2 bigide (stable FPC);
115	127		- x86_64-gtk3 bigide (stable FPC);
116	128		- x86_64-qt5 bigide (oldstable FPC);
117	129		- x86_64-qt6 bigide (stable FPC);
118	130		- i386-win32 bigide (stable FPC);
119	131		- Tests for Codetools (main FPC).
120	132
121	133		All others can be triggered manually via GitLab web interface.
122	134
123	135		In GitLab web interface you can notice Build menu item at the left. By clicking Build-\>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).
124	136
125	137		Important notice for Qt5/Qt6 jobs:
126	138
127	139		They use cached results from stage 3. In absolute majority of the builds this should not cause any problems. But still if stage 3 does not pass or if you get Qt5/Qt6 widgetset build failure related to Qt5Pas/Qt6Pas version mismatch or missing cache, make sure to go to the Pipelines page and do the following:
128	140
129	141		1. Stop the currently running pipeline if needed.
130	142		2. Press Run pipeline button (you will be asked about defining variables, just skip this step (we don't use them) and confirm running pipeline).
131	143		3. In case pipeline failed to pass, press Clear runner caches button and then rerun pipeline by pressing Run pipeline button again.
132	144
133	145		---
134	146		From the Free Pascal wiki, page "Lazarus Team - Git Workflows", as it stood on 2023-11-22 after a change by Maxim, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
135	147		Category: Lazarus
136	148		Category: Revision control
137	149		Category: SOPs

Back to history