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

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

intrigeri's avatar
intrigeri committed
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
For general GitLab usage information, see the
[[!tails_gitlab help/user desc="GitLab user documentation"]].
intrigeri's avatar
intrigeri committed
12 13

[[!toc levels=2]]

intrigeri's avatar
intrigeri committed
# Getting started

17 18 19
To create your GitLab account, visit the [[!tails_gitlab users/sign_in
desc="registration page"]] in a web browser.

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

intrigeri's avatar
intrigeri committed
23 24
Later on, you will probably need to [[request more

26 27 28 29 30 31 32 33
# 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"]].

<a id="metadata"></a>
intrigeri's avatar
intrigeri committed
# How we use GitLab metadata
36 37 38 39

On GitLab, issues and merge requests have metadata.

Being consistent in the use of GitLab metadata makes collective work
intrigeri's avatar
intrigeri committed
41 42 43 44 45 46 47 48 49 50

## 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.

## Status

### Open issues

Each open issue can have up to 1 status label:

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

 - _Doing_: someone is actively working on this issue

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

60 61 62 63 64 65 66
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.

67 68 69 70 71
### Closed issues

Closing an issue means one of:

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

73 74 75 76 77 78
    - 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

80 81 82 83
   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

85 86 87 88
    - explains why you're rejecting it
    - adds the _Rejected_ label (`/label Rejected`)

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

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

92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
    - mentions the other, duplicated issue
    - adds the _Duplicate_ label (`/label Duplicate`)

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

## Assignee

We use the _Assignee_ field in a way that helps us organize share our
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

sajolida's avatar
sajolida committed
So in general, issues and merge requests should not be assigned to anyone.
108 109 110 111 112 113 114 115

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

 - Someone is actively working on it.

 - The task is both important and urgent.

intrigeri's avatar
intrigeri committed
116 117
 - The milestone is set to the next Tails release.
   See the [[milestone|GitLab#milestone]] section for details.
118 119 120 121 122 123 124 125 126 127 128 129

 - 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
 - It is about the parent tracking issue for a large project with several
131 132 133 134 135 136 137 138 139 140 141 142 143
   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
For issues that are on the Tails [[!tails_roadmap]], the milestone is set
145 146
to a year, until it makes sense to target a specific release.

intrigeri's avatar
intrigeri committed
Postponing to the next milestone more than once is not business
148 149 150
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
any milestone in the first place.
152 153 154 155 156

## Priority

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

 - _P:Low_: it would be good to do this, but it's unlikely
158 159
   that current Tails contributors find time to work on it
   any time soon
160 161 162 163
 - _P:Normal_, or no such label: this is the general case
 - _P:Elevated_
 - _P:High_
 - _P:Urgent_

intrigeri's avatar
intrigeri committed
165 166 167 168
See the
[[!tails_gitlab groups/tails/-/labels?search=P%3A
desc="list of priority labels"]].

169 170
## Category

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

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

intrigeri's avatar
intrigeri committed
175 176 177 178
See the
[[!tails_gitlab groups/tails/-/labels?search=C%3A
desc="list of category labels"]].

179 180 181
## Type of work

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

For example:

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

intrigeri's avatar
intrigeri committed
195 196 197 198
See the
[[!tails_gitlab groups/tails/-/labels?search=T%3A
desc="list of type of work labels"]].

199 200 201 202 203 204 205 206 207 208 209 210
## Other labels

 - _Starter_: issues flagged as *Starter* can be a good pick for new contributors
   [[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

211 212
A GitLab issue can have a
[[!tails_gitlab help/user/markdown.html#task-lists desc="task list"]].
213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230

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
[[!tails_gitlab help/user/project/issues/confidential_issues.html desc="confidential"]]
232 233 234 235 236 237
when creating it or at any later time.

A confidential issue is visible only by:

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

243 244 245 246 247 248 249 250 251 252 253
<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.


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

<a id="document-progress"></a>
intrigeri's avatar
intrigeri committed
259 260
# How to document progress

261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283
## 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 duty from frontdesk (#8420)

## Report progress or failure

intrigeri's avatar
intrigeri committed
It is important to:

intrigeri's avatar
intrigeri committed
286 287 288 289 290 291 292
 - 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.

293 294 295 296 297 298 299 300
For details, see how we use the [[assignee|GitLab#assignee]]
and [[milestone|GitLab#milestone]] information.

# How to propose, review, and merge changes

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

intrigeri's avatar
intrigeri committed
301 302 303 304

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

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

308 309
<a id="discussions"></a>

310 311 312 313 314 315 316 317 318 319
## 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.

320 321 322
For more information, see the GitLab documentation about [[!tails_gitlab
help/user/discussions/ desc="Discussions"]].

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

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

intrigeri's avatar
intrigeri committed
## Acting upon input requests
331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349

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](

 - 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
# Email interface
351 352 353 354 355 356 357

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

 - Stay informed of what's happening in GitLab

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

 - Participate in [[!tails_gitlab help/user/discussions/ desc="discussions"]]
361 362 363
   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

365 366 367 368 369
   Write your email just as if you [replied from the
   In particular:

    - Write your email in
      [[!tails_gitlab help/user/markdown.html Markdown]].
    - You can use
      [[!tails_gitlab help/user/project/quick_actions.html desc="Quick actions"]].
373 374

 - Create new issues
sajolida's avatar
sajolida committed

   See [[!tails_gitlab help/user/project/issues/managing_issues.html#new-issue-via-email desc="New issue via email"]]
377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403
   in the GitLab documentation.

# 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
whose name starts with *Core work*.

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

intrigeri's avatar
intrigeri committed
405 406 407 408 409 410 411 412 413 414 415 416 417 418 419
<a id="operations"></a>

# Operations

## Administration of GitLab

Our friends at <> host [[!tails_gitlab desc="our GitLab

The Tails [[system administrators|working_together/roles/sysadmins]]
administrate this GitLab instance.

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

## Access control
intrigeri's avatar
intrigeri committed

intrigeri's avatar
intrigeri committed
### Objects
intrigeri's avatar
intrigeri committed
422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441

 - _Canonical Git repo_: the authoritative [[!tails_gitlab tails/tails]]
   repository, hosted on GitLab

 - _Major branches_: `master`, `stable`, `testing`, `devel`,
   and possibly `feature/bullseye`

 - _Release tags_: a signed Git tag that identifies the source code
   used to build a specific Tails release; currently all tags
   in the authoritative `tails.git` repository are release tags;
   the tag name is a version number, with '~' replaced by '-'.

 - _Particularly sensitive data_: confidential data that specific teams
   like Fundraising and Accounting need to handle, but that other
   contributors generally don't need direct access to. This definitely
   include issues; this might include Git repositories at some point.

   Note that as of 2020-03-29, it is undefined:

    - What subset of this data can go to a web-based issue tracker or not.<br/>
intrigeri's avatar
intrigeri committed
      This was already a problem with Redmine.<br/>
intrigeri's avatar
intrigeri committed
443 444 445 446 447 448 449
      Fixing this will require discussions between various stakeholders.

    - What subset of this data could live in a cleartext Git
      repository hosted here or there, as opposed to requiring
      end-to-end encryption between members of these teams.
      This is a hypothetical problem for now.

intrigeri's avatar
intrigeri committed
### Subjects
intrigeri's avatar
intrigeri committed
451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490

 - An _admin_ can do anything that other roles can, and:
   - can delete issues
   - can edit team membership
   - MUST comply with our "Level 3" security policy
   - can view issues that contain particularly sensitive data

 - A _committer_:
   - can push and force-push to any ref in the canonical Git repo,
     including major branches and release tags;<br/>
     incidentally, this ensures the following requirement is met:
   - their branches are picked up by Jenkins; it follows that they
     MUST comply with our "Infrastructure" security policy
   - can merge MRs into major branches
   - can modify issues metadata
   - is allowed to view confidential issues in the [[!tails_gitlab tails/tails]]
     GitLab project; that's OK, because particularly sensitive data
     lives somewhere else, with stricter access control
   - can edit other users' comments
   - MUST comply with our "Level 3" security policy

 - A _regular, particularly trusted contributor_:
   - can push and force-push to a subset of refs in the canonical Git repo;
     this subset MUST NOT include any major branch nor release tag;<br/>
     this is required to ensure the following requirement is met:
   - their branches are picked up by Jenkins; it follows that they
     MUST comply with our "Infrastructure" security policy
   - can modify issues metadata
   - is allowed to view confidential issues in the [[!tails_gitlab tails/tails]]
     GitLab project; that's OK, because particularly sensitive data
     lives somewhere else, with stricter access control

 - A _regular contributor_:
   - can fork the Git repositories and push changes to their own fork
   - can modify issues metadata
   - is allowed to view confidential issues in the [[!tails_gitlab tails/tails]]
     GitLab project; that's OK, because particularly sensitive data
     lives somewhere else, with stricter access control

 - _Anybody with a GitLab account_ on the instance we use:
intrigeri's avatar
intrigeri committed
491 492
   - can view and submit issues in public projects
   - can submit MRs in public projects
intrigeri's avatar
intrigeri committed

intrigeri's avatar
intrigeri committed
### Implementation
intrigeri's avatar
intrigeri committed

intrigeri's avatar
intrigeri committed
496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520
<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]]
[[|about/contact#tails-sysadmins]] 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

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

intrigeri's avatar
intrigeri committed
#### Relevant GitLab doc
intrigeri's avatar
intrigeri committed

523 524 525 526
 - [[!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/ desc="Groups"]]
intrigeri's avatar
intrigeri committed

intrigeri's avatar
intrigeri committed
#### Access levels
intrigeri's avatar
intrigeri committed

530 531 532
We use the [[!tails_gitlab
desc="Protected branch flow"]]:
intrigeri's avatar
intrigeri committed
533 534 535 536 537 538 539 540 541 542 543

 - 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.