GitLab.mdwn 18.9 KB
Newer Older
1
[[!meta title="GitLab source code and bug tracker"]]
sajolida's avatar
sajolida committed
2

intrigeri's avatar
intrigeri committed
3
Tails issues and code are managed in [[!tails_gitlab "" desc="GitLab"]].
4

intrigeri's avatar
intrigeri committed
5
This page focuses on aspects of GitLab usage that are specific to Tails.
6
7
8
9

This workflow is not set in stone: it will evolve based on what
we learn while using GitLab.

intrigeri's avatar
intrigeri committed
10
For general GitLab usage information, see the
intrigeri's avatar
intrigeri committed
11
[[!tails_gitlab help/user/index.md desc="GitLab user documentation"]].
intrigeri's avatar
intrigeri committed
12
13

[[!toc levels=2]]
14

intrigeri's avatar
intrigeri committed
15
# Getting started
16

intrigeri's avatar
intrigeri committed
17
18
19
If you were using Redmine previously, read [[how to transition to
GitLab|GitLab/transition]]. Else, to create your GitLab account, visit the
[[!tails_gitlab users/sign_in desc="registration page"]] in a web browser.
20

21
22
Then you will be allowed to open new issues, create merge requests, and fork
your own copy of our repositories.
23

24
25
26
27
28
Later on, you will probably need to:

 - [[!tails_gitlab profile/keys desc="Add your SSH key"]]
   to your GitLab account
 - [[Request more credentials|GitLab#request-access]]
29

30
31
32
33
The first time you connect over SSH to a Git repository hosted on our GitLab,
you will be prompted to verify the server's SSH host key. Here are the
corresponding fingerprints:

intrigeri's avatar
intrigeri committed
34
35
36
 - ECDSA: `SHA256:AOj9ec6hRjN7fNnjXMlmPum7dZWRd5oJKAuo4UGAxxs`
 - Ed25519: `SHA256:mtZeDs2+KKLZ8kJOvmrGoTCuszqc29DOyH6MZaqtlss`
 - RSA: `SHA256:JuwD+e+wOas+2JtDdF0BHu+9RAIJOhWI+2VkjuZ6Znk`
37

38
39
40
41
42
43
44
45
# Group and projects

All our work is tracked in projects under the [[!tails_gitlab tails
desc="tails group"]].

The main Git repository and most issues live in the [[!tails_gitlab tails/tails
desc="tails/tails project"]].

46
<a id="metadata"></a>
intrigeri's avatar
intrigeri committed
47
# How we use GitLab metadata
48
49
50
51

On GitLab, issues and merge requests have metadata.

Being consistent in the use of GitLab metadata makes collective work
intrigeri's avatar
intrigeri committed
52
smoother.
53
54
55
56
57
58

## Title and description

The title should be a short but clear description of what this is about.
Some people are case sensitive, please try to consider that.

intrigeri's avatar
intrigeri committed
59
<a id="status"></a>
60
61
62
63
## Status

### Open issues

64
Each open issue can have up to 1 status label:
65

66
 - _To Do_: it would be good if someone worked on this issue
67

68
 - _Doing_: someone is actively working on this issue
69

70
 - _Needs Validation_: a resolution has been proposed and needs to be reviewed.
71
72
   For details, see our [[merge policy|/contribute/merge_policy]].

73
74
75
76
77
78
79
The main advantage of using these labels is to organize and visualize issues on
[[!tails_gitlab help/user/project/issue_board.html desc="Issue Boards"]].

Some teams use a workflow that depends on accurately using these labels.

Apart of that, you may consider these labels as optional.

80
81
82
83
84
### Closed issues

Closing an issue means one of:

 - The bugfix or feature the issue is about:
sajolida's avatar
sajolida committed
85

86
87
88
89
90
91
    - was merged and will be in a future release
    - or is already available to our users

   The _Milestone_ value tells in which case we are.

 - We've rejected it.
sajolida's avatar
sajolida committed
92

93
94
95
96
   For example: it does not fit into Tails' mission,
   or the problem shall be resolved elsewhere than in Tails.

   To reject an issue, create a comment that:
sajolida's avatar
sajolida committed
97

98
    - explains why you're rejecting it
99
    - adds the _Rejected_ label (`/label ~Rejected`)
100
101

 - It duplicates another issue.
sajolida's avatar
sajolida committed
102

103
   To mark an issue as a duplicate, create a comment that:
sajolida's avatar
sajolida committed
104

105
    - mentions the other, duplicated issue
106
    - adds the _Duplicate_ label (`/label ~Duplicate`)
107
108
109
110
111

<a id="assignee"></a>

## Assignee

intrigeri's avatar
intrigeri committed
112
We use the _Assignee_ field in a way that helps us organize our
113
114
115
116
117
118
119
work as a team, focus on what matters most currently, and avoid
individual over-commitment & feelings of failure.

To this aim, most tasks should be up for grabs for anyone who has spare capacity
and the required skills: [Don't Lick the
Cookie](https://www.benday.com/2016/10/21/scrum-dont-lick-the-cookie/).

sajolida's avatar
sajolida committed
120
So in general, issues and merge requests should not be assigned to anyone.
121
122
123
124
125
126
127
128

This being said, we do assign them if at least one of these conditions is
met:

 - Someone is actively working on it.

 - The task is both important and urgent.

intrigeri's avatar
intrigeri committed
129
130
 - The milestone is set to the next Tails release.
   See the [[milestone|GitLab#milestone]] section for details.
131
132
133
134
135
136
137
138
139
140
141
142

 - We did all the work we could on this task already and now have to
   track progress on a blocker that we cannot address ourselves.
   For example, regularly tracking progress and pinging on patches
   we've submitted upstream.

 - Only one of us can complete the task. This helps identify
   bottlenecks, high bus factor, and over-commitment.

 - Sponsor deliverables that are managed under the "let's decide
   a long time in advance who exactly will do each task" paradigm.

intrigeri's avatar
intrigeri committed
143
 - It is about the parent tracking issue for a large project with several
144
145
146
147
148
149
150
151
152
153
154
155
156
   subtasks that will be tackled by different people, and we need
   someone to coordinate the project.

<a id="milestone"></a>

## Milestone

Different teams and contributors use the _Milestone_ value differently:

 - Some teams try their best to treat it as a commitment, that other Tails
   contributors should be able to rely on.
 - Others use it as a pool of tasks they want to have on their short-term radar.

intrigeri's avatar
intrigeri committed
157
For issues that are on the Tails [[!tails_roadmap]], the milestone is set
158
159
to a year, until it makes sense to target a specific release.

intrigeri's avatar
intrigeri committed
160
Postponing to the next milestone more than once is not business
161
162
163
as usual — it's a red flag. Ideally, the underlying problem should be identified
and addressed: for example, the assignee might need help or be over-committed;
the team could be under-staffed; or perhaps the task should simply not have
intrigeri's avatar
intrigeri committed
164
any milestone in the first place.
165
166
167
168
169

## Priority

Every open issue must have exactly 0 or 1 of these labels:

170
 - _P:Low_: it would be good to do this, but it's unlikely
171
172
   that current Tails contributors find time to work on it
   any time soon
173
174
175
176
 - _P:Normal_, or no such label: this is the general case
 - _P:Elevated_
 - _P:High_
 - _P:Urgent_
177

intrigeri's avatar
intrigeri committed
178
179
180
181
See the
[[!tails_gitlab groups/tails/-/labels?search=P%3A
desc="list of priority labels"]].

182
183
## Category

184
We classify issues with labels whose name starts with _C:_.
185

186
For example, _C:Email Client_ or _C:Installation_.
187

intrigeri's avatar
intrigeri committed
188
189
190
191
See the
[[!tails_gitlab groups/tails/-/labels?search=C%3A
desc="list of category labels"]].

192
193
194
## Type of work

To indicate the type of work that's needed to complete the next step
195
on an issue, we use labels whose name starts with _T:_.
196
197
198

For example:

199
200
 - _T:Debian_: the work shall be done in Debian
 - _T:End-user documentation_: everything below [[doc]] and [[support]]
201
    on our website
202
 - _T:Contributors documentation_: everything below [[contribute]]
203
    on our website
204
 - _T:Wait_: we are waiting/tracking actions we need non-Tails
205
   people to do, outside of Tails
206
 - _T:Website_: website work not covered by other options
207

intrigeri's avatar
intrigeri committed
208
209
210
211
See the
[[!tails_gitlab groups/tails/-/labels?search=T%3A
desc="list of type of work labels"]].

212
213
## Other labels

intrigeri's avatar
intrigeri committed
214
 - _Starter_: issues flagged as *Starter* can be a good pick for new contributors.
215
216
217
218
219
220
221
222
223
   [[Learn more|contribute/working_together/criteria_for_starter_tasks/]].

## Relationships between issues

Arguably, GitLab CE is a bit limited when it comes to expressing semantic
relationships between issues. Here is how we can overcome these limitations.

### Parent/subtask and Blocks relationship

224
225
A GitLab issue can have a
[[!tails_gitlab help/user/markdown.html#task-lists desc="task list"]].
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243

Every task is a task list can be:

 - free-form text

 - a `#NNNN` link to another issue, that needs to be closed
   before the issue with the task list can itself be closed.

### Related issues

You can list related issues either in the description or in a comment.

Either way, this adds a message in the Activity stream of the
referenced issue, with a link to the referencing issue.

## Confidential issues

You can make an issue
244
[[!tails_gitlab help/user/project/issues/confidential_issues.html desc="confidential"]]
245
246
247
248
249
250
when creating it or at any later time.

A confidential issue is visible only by:

 - whoever created it
 - project members with at least
251
252
   [[!tails_gitlab help/user/permissions.html#project-members-permissions
   desc="Reporter"]]
intrigeri's avatar
intrigeri committed
253
254
   access; that is, for our [[!tails_gitlab tails/tails desc="main GitLab
   project"]]: most past and present Tails contributors
255

256
257
258
259
260
261
262
263
264
265
266
<div class="caution">

Only share the URL of an attachment with people you want to allow downloading
that file.

In contrast with Redmine, that enforced access control on attachments, with
GitLab, anyone can download <emph>any</emph> attachment if they know its URL.
This applies equally to attachments added to a confidential issue.

</div>

267
If your team regularly manipulates confidential data, then its issues live under
intrigeri's avatar
intrigeri committed
268
a dedicated GitLab project, with a different set of members, and possibly
269
only visible to project members.
270

271
<a id="document-progress"></a>
intrigeri's avatar
intrigeri committed
272
273
# How to document progress

274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
## Create and update issues

When you start working on a task, update the corresponding GitLab issue, after
creating one if needed: replace any status label with the *Doing* label.
For details about labels, see [[metadata|GitLab#metadata]].

All the knowledge useful to the others should be kept on that issue,
or at least linked from there.

Please keep the issues you are working on updated, so that they reflect the
actual status of the task, and especially the next thing to do for it to
be completed.

When committing changes that will resolve an issue once merged, please
include `#NNNN` in the commit message, _NNNN_
being the issue number. Then, GitLab will automatically reference this
commit on the corresponding issue, once the branch is pushed to our
[[Git repository|contribute/Git]]. For example:

    Remove tails@boum.org duty from frontdesk (#8420)

## Report progress or failure

intrigeri's avatar
intrigeri committed
297
It is important to:
298

intrigeri's avatar
intrigeri committed
299
300
301
302
303
304
305
 - Keep the team informed of how you feel committed to issues assigned to you,
   and about the timeline you're envisioning.
 - Avoid individual over-commitment & feelings of failure.

If you don't think you will manage to work on an issue any time soon,
it's often best to make this clear on the issue, or to de-assign yourself.

306
307
308
309
310
For details, see how we use the [[assignee|GitLab#assignee]]
and [[milestone|GitLab#milestone]] information.

# How to propose, review, and merge changes

311
We use [[!tails_gitlab help/user/project/merge_requests/index.md desc="Merge Requests"]]
312
313
(aka. MRs) to propose, review, and merge changes.

intrigeri's avatar
intrigeri committed
314
315
316
317
See:

 - [[how to propose, review, and merge changes|contribute/merge_policy]]
 - [[how to participate in discussions|GitLab#discussions]]
318

intrigeri's avatar
intrigeri committed
319
# How to request and provide input
320

321
322
<a id="discussions"></a>

323
324
325
326
327
328
329
330
331
332
## How to participate in discussions

You can comment on issues and merge requests.
Our [[contribute/working_together/code_of_conduct]] applies.

If you want to start a new discussion, please use _Start thread_ instead of
_Comment_: a thread can be marked as resolved, while a comment cannot.
This helps keeping track of which discussions have reached a conclusion,
and which ones are still pending.

333
334
335
336
337
To start a thread, type your message and choose _Start thread_ in the
_Comment_ split button.

[[!img start_thread.png link="no" alt=""]]

338
339
340
For more information, see the GitLab documentation about [[!tails_gitlab
help/user/discussions/index.md desc="Discussions"]].

intrigeri's avatar
intrigeri committed
341
## Requesting input from someone else
342

intrigeri's avatar
intrigeri committed
343
344
If you need input from someone else on an issue or merge request,
ask your question in a comment there, mentioning them
345
346
347
with their GitLab login name: `@nick`. GitLab will send them
an email notification about it and add it to their To-Do list.

348
349
350
351
352
If you want to raise attention of every single member of a team, mention it with
the name of the corresponding [[!tails_gitlab explore/groups desc="group"]]:
`@xyz-team`. GitLab will send an email notification about it to every member
of this group, and add it to their To-Do list.

353
354
355
356
357
358
Please note that the `root` user is part of all groups only because it is used
for the administration of our GitLab instance. There's no human being behind
that account and its notifications are turned off. Do not expect to receive
answers from that user, make sure to mention other appropriate users and groups
instead.

intrigeri's avatar
intrigeri committed
359
## Acting upon input requests
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378

It's important to provide requested information as quickly as you can,
to make the Tails contribution process more efficient and enjoyable.

When input is requested from you on an issue or merge request with `@nick`:

 - GitLab adds an item in your
   [To-Do list](https://gitlab.tails.boum.org/dashboard/todos).

 - GitLab may send you an email notification

   Please ensure your GitLab email notification settings and your email setup
   allow you to receive and notice these messages.

When you receive such a request, if you cannot provide the requested input
immediately, you're responsible for keeping track of this task, for example via
the To-Do list, or by creating a new issue assigned to yourself, or using
whatever personal organization tools work for you.

intrigeri's avatar
intrigeri committed
379
# Email interface
380
381
382
383
384
385
386

Using the email address registered with your GitLab account,
you can:

 - Stay informed of what's happening in GitLab

   To do so, enable email
387
   [[!tails_gitlab help/user/profile/notifications.html desc="notifications"]].
388

389
 - Participate in [[!tails_gitlab help/user/discussions/index.md desc="discussions"]]
390
391
392
   on issues and merge requests, modify issues metadata

   To do so, reply to an email notification you've received from GitLab.
sajolida's avatar
sajolida committed
393

394
395
396
397
398
   Write your email just as if you [replied from the
   web].
   In particular:

    - Write your email in
399
      [[!tails_gitlab help/user/markdown.html desc="Markdown"]].
400
    - You can use
401
      [[!tails_gitlab help/user/project/quick_actions.html desc="Quick actions"]].
402
403

 - Create new issues
sajolida's avatar
sajolida committed
404

405
   See [[!tails_gitlab help/user/project/issues/managing_issues.html#new-issue-via-email desc="New issue via email"]]
406
407
   in the GitLab documentation.

408
409
410
411
<a id="api"></a>

# Scripts that use the GitLab API

sajolida's avatar
sajolida committed
412
We have several scripts that query or manipulate data using the GitLab API:
413
414
415
416
417
for example, [[!tails_gitweb bin/generate-changelog]] and [[!tails_gitweb
bin/generate-report]].

To use them:

intrigeri's avatar
intrigeri committed
418
419
420
* Install a recent enough `python3-gitlab` Debian package:

        if [ "$(lsb_release --short --codename)" = buster ]; then
intrigeri's avatar
intrigeri committed
421
           sudo apt install python3-gitlab/bullseye
intrigeri's avatar
intrigeri committed
422
423
424
        else
           sudo apt install python3-gitlab
        fi
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441

* Configure your `~/.python-gitlab.cfg`.

  You need at least this content:

        [global]
        ssl_verify = true

        [Tails]
        url = https://gitlab.tails.boum.org
        per_page = 100
        private_token = XXX

  In the `Tails` section, set the value of the `private_token` option to a
  GitLab API token for your own user. To generate such a token,
  visit [[!tails_gitlab profile/personal_access_tokens]].

442
443
* If you are working from Tails, run the scripts using `torsocks`.

intrigeri's avatar
intrigeri committed
444
445
<a id="core-work"></a>

446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
# Core teams' work

Some of the teams who do
[[Core work|contribute/working_together/roles]] (be it paid or done on
a volunteer basis) maintain GitLab metadata in order to:

 * provide visibility on what they doing & their priorities;

 * give the Tails community some power over setting these priorities;

 * encourage the Tails community to help core workers define their
   priorities: they sometimes have a hard time deciding by themselves
   how they should spend their time on what matters the most to
   the project.

To track this, these teams use
462
463
[[!tails_gitlab groups/tails/-/labels?utf8=✓&search=Core+work
desc="labels whose name starts with *Core work*"]].
464
465
466
467
468
469
470

The teams who use this mechanism are more than happy to get feedback
about these priorities: both addition and removal suggestions are
welcome. Please check the mission statement for the corresponding team
first, to ensure you're not asking them to do something that's outside
of the scope of their job. And please justify your suggestions.
Please check these views once in a while and talk to us! :)
intrigeri's avatar
intrigeri committed
471

intrigeri's avatar
intrigeri committed
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
<a id="ci"></a>

# GitLab CI

Tails system administrators are currently experimenting with [[!tails_gitlab
help/ci/README.md desc="GitLab CI"]] for some quality assurance checks that
don't require building or booting Tails images: [[!tails_gitlab
tails/sysadmin/-/issues/17740]].

## Experimental

Please consider this work as experimental and don't rely on it for making
decisions. In particular:

 - Don't trust the CI runners. As a consequence, don't trust the results of
   CI pipelines.

 - Don't rely on the CI runners being in working shape.

*Why?* Because the CI runner we are using at the moment is running on a test
infrastructure, that's not managed in the same way as our production
infrastructure. For example, it is not automatically monitored, and security
intrigeri's avatar
intrigeri committed
494
updates are not consistently applied in a timely manner.
intrigeri's avatar
intrigeri committed
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510

We will let you know once our GitLab CI setup is in production.

## Feedback and patches are welcome

Please [[give feedback and
input|contribute/working_together/roles/sysadmins/#communication]] about this
topic to Tails sysadmins.

For example, you can propose new tests that we could run on GitLab CI.
Please explain what the expected benefit would be for your work or for Tails
users: this will help us prioritize our work.

Finally, you can send merge requests that improve the existing jobs
or add new ones: [[!tails_gitweb .gitlab-ci.yml]].

511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
<a id="access-control"></a>

# Access control

<a id="request-access"></a>

## Requesting access

If you need to do something in GitLab and you appear to lack the
needed credentials, please ask the Tails
[[system administrators|working_together/roles/sysadmins#communication]]
to grant you more power.

For example, you will need "Reporter" access on the [[!tails_gitlab
tails/tails]] project in order to add labels or assign issues.

## Adding/removing access

Do not grant access via the web interface:

 - Such manual changes would be later overwritten by automated processes.
 - Manual changes can easily have side effects that violate our access control
   requirements.

Instead, after following the relevant process (if any),
request the access modification from the Tails
[[system administrators|working_together/roles/sysadmins#communication]].

## Relevant GitLab doc

 - [[!tails_gitlab help/user/permissions.html desc="Permissions"]]
 - [[!tails_gitlab help/user/project/merge_requests/authorization_for_merge_requests.html desc="Authorization for Merge requests"]]
 - [[!tails_gitlab help/user/project/protected_branches.html desc="Protected Branches"]]
 - [[!tails_gitlab help/user/group/index.md desc="Groups"]]

## Access levels

We use the [[!tails_gitlab
help/user/project/merge_requests/authorization_for_merge_requests.html#protected-branch-flow
desc="Protected branch flow"]]:

 - Our major branches and release tags are marked as "Protected".
 - Committers get "Maintainer" access.
 - Regular, particularly trusted contributors, who are not granted full commit
   access but have access to our CI, get "Developer" access. They can push
   a topic branch to the canonical Git repository and our CI will pick it up.
   They can also modify any non-protected topic branch.
 - Other contributors get access strictly lower than "Developer".
   They push topic branches to their own fork of the repository and
   create merge requests.
 - Our Jenkins CI jobs generation process is the same as in pre-GitLab days.

intrigeri's avatar
intrigeri committed
563
564
565
566
<a id="operations"></a>

# Operations

567
See our documentation about [[GitLab for Tails
568
sysadmins|contribute/working_together/roles/sysadmins/GitLab]].