GitLab.mdwn 9.8 KB
Newer Older
intrigeri's avatar
intrigeri committed
1
Tails issues are managed in [[!tails_gitlab "" desc="GitLab"]].
2

intrigeri's avatar
intrigeri committed
3 4 5 6 7
This page focuses on aspects of GitLab usage that are specific to Tails.
For general GitLab usage information, see the [GitLab user documentation]
(https://docs.gitlab.com/ce/user/).

[[!toc levels=2]]
8

intrigeri's avatar
intrigeri committed
9
# Getting started
10

intrigeri's avatar
intrigeri committed
11
XXX: create account
12

intrigeri's avatar
intrigeri committed
13 14 15 16
Later on, if you need to do something in GitLab and you appear to lack the
needed credentials, please ask
[[tails-sysadmins@boum.org|about/contact#tails-sysadmins]] to give you
more power.
17 18

<a id="metadata"></a>
intrigeri's avatar
intrigeri committed
19
# How we use GitLab metadata
20 21 22 23

On GitLab, issues and merge requests have metadata.

Being consistent in the use of GitLab metadata makes collective work
intrigeri's avatar
intrigeri committed
24
smoother.
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212

## 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 must have exactly 0 or 1 of these labels:

 - No such label: newly created issue that needs to be triaged
   by the UX team and Foundations Team.

 - "1. To do": it would be good if someone worked on this issue

 - "2. Doing": someone is actively working on this issue

 - "3. Needs Validation": a resolution has been proposed and needs to be reviewed.
   For details, see our [[merge policy|/contribute/merge_policy]].

### Closed issues

Closing an issue means one of:

 - The bugfix or feature the issue is about:
 
    - 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.
 
   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:
   
    - explains why you're rejecting it
    - adds the _Rejected_ label (`/label Rejected`)

 - It duplicates another issue.
 
   To mark an issue as a duplicate, create a comment that:
   
    - 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
Cookie](https://www.benday.com/2016/10/21/scrum-dont-lick-the-cookie/).

So in general, issues and merge requests should not be assigned to anyone. 

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.

 - The _Target version_ is set to the next Tails release.
   See the "Target version" section above for details.

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

 - It is about the parent ticket for a large project with several
   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.

For issues that are on the Tails [[!tails_roadmap]], the _Target version_ is set
to a year, until it makes sense to target a specific release.

Postponing to the next _Target version_ more than once is not business
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
a _Target version_ in the first place.

## 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
   that current Tails contributors find time to work on it
   any time soon
 - _P: Normal_, or no such label: this is the general case
 - _P: Elevated_
 - _P: High_
 - _P: Urgent_

## Category

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

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

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

For example:

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

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

A GitLab issue can have a [task
list](https://docs.gitlab.com/ce/user/markdown.html#task-lists).

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
[confidential](https://docs.gitlab.com/ce/user/project/issues/confidential_issues.html)
when creating it or at any later time.

A confidential issue is visible only by:

 - whoever created it
 - project members with at least
   [Reporter](https://docs.gitlab.com/ce/user/permissions.html#project-members-permissions)
   access; that is, for our main GitLab project: most Tails contributors

If your team regularly manipulates confidential data, then its issues live under
its own GitLab project, with a different set of members, and possibly configured
so that new issues are confidential by default.

intrigeri's avatar
intrigeri committed
213 214 215
# How to document progress

See [[contribute/working_together/document_progress]].
216

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

intrigeri's avatar
intrigeri committed
219
## Requesting input from someone else
220 221 222 223 224 225

If you want to work on an issue but you need some input from someone
else, ask your question on a comment on the issue, mentioning them
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
226
## Acting upon input requests
227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245

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
246 247 248 249
# How to submit and review merge requests

See the [[contribute/merge_policy]].

intrigeri's avatar
intrigeri committed
250
# Email interface
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303

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

 - Stay informed of what's happening in GitLab

   To do so, enable email
   [notifications](https://docs.gitlab.com/ce/user/profile/notifications.html).

 - Participate in [discussions](https://docs.gitlab.com/ce/user/discussions/)
   on issues and merge requests, modify issues metadata

   To do so, reply to an email notification you've received from GitLab.
   
   Write your email just as if you [replied from the
   web].
   In particular:

    - Write your email in
      [Markdown](https://docs.gitlab.com/ce/user/markdown.html).
    - You can use
      [Quick actions](https://docs.gitlab.com/ce/user/project/quick_actions.html).

 - Create new issues
 
   See [New issue via email](https://docs.gitlab.com/ce/user/project/issues/managing_issues.html#new-issue-via-email)
   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
[labels](https://gitlab.tails.boum.org/tails-team/-/labels)
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! :)