Commit 62f3541a authored by intrigeri's avatar intrigeri
Browse files

Start migrating contributors doc to GitLab (tails-team/gitlab-migration#30)

parent 373a9dea
......@@ -27,7 +27,7 @@ Most of the possible candidate goals that were
critical. Pursuing these would require substantial effort, that is
better put into other Tails improvements. Therefore, they have not
made their way into our [[!tails_roadmap]]. Some have low-priority
tickets on [[!tails_redmine desc="Redmine"]], meaning that patches are
tickets on [[!tails_gitlab desc="GitLab"]], meaning that patches are
welcome, but we do not feel committed, as a project, to make
it happen.
......
......@@ -3,7 +3,7 @@
See also:
* the [[corresponding design document|contribute/design/incremental_upgrades]];
* the tickets with the _Incremental upgrades_ category on [[!tails_redmine "" desc="Redmine"]].
* the tickets with the _C: Upgrader_ label on [[!tails_gitlab "" desc="GitLab"]].
# Random ideas for future improvements
......
[[!meta title="Bugs"]]
If you've found a bug in Tails, please read [[doc/first_steps/bug_reporting]].
We don't use this section anymore, see [[contribute/working_together/Redmine]] instead.
......@@ -132,10 +132,8 @@ Tools for contributors
- Source code: [[Git repositories|contribute/git]]
- [[!tails_roadmap desc="Roadmap"]]
- [[Redmine bug tracker|contribute/working_together/Redmine]]
- [[Starter tasks|starter_tasks]] for new contributors
- [Tasks](https://redmine.tails.boum.org/code/projects/tails/issues)
can be filtered by type of work (see links in the sidebar)
- [[GitLab|contribute/working_together/GitLab]]
- [[Starter tasks|starter_tasks]] for new contributors
- [[Building a Tails image|contribute/build]]
- [[Build a local copy of the website|contribute/build/website]]
- [[Customize Tails|contribute/customize]]
......@@ -157,7 +155,7 @@ you might need some guidance.
Here is a list of mentors who can help with
specific tasks. Feel free to talk to them if you plan to work on anything related to their
field of expertise, for example
by assigning them tickets on Redmine or <a href="#talk">talking to us</a>
by assigning them issues on GitLab or <a href="#talk">talking to us</a>
using the usual communication channels.
- AppArmor: intrigeri, jvoisin, u
......
......@@ -796,7 +796,7 @@ through the necessary steps.
## 3.5 Feedback
Users can send feedback in several ways to Tails developers.
A [[!tails_redmine desc="task tracker"]] is available.
A [[!tails_gitlab desc="task tracker"]] is available.
Users can also send email to the private [[developers mailing
list|about/contact#tails]] or to the private [[support mailing
list|about/contact#tails-support-private]].
......
......@@ -57,7 +57,7 @@ upstream... which sometimes implies to write a patch ourselves.
## Pick up a task
We use [[!tails_redmine "" desc="Redmine"]] to manage
We use [[!tails_gitlab "" desc="GitLab"]] to track
our lists of tasks and bugs, as well as our [[!tails_roadmap]].
If you already know which one of the listed tasks you want to tackle
and it has the *Code* Type of work, then you can probably
......@@ -103,8 +103,8 @@ So you know what bug you want to fix, what feature you want to
implement. At this point, we advise you to:
1. **Gather results of previous research and discussions** on the
topic you are interested in. Search this website, [[!tails_redmine ""
desc="tickets on Redmine"]] and the [tails-dev@boum.org mailing list
topic you are interested in. Search this website, [[!tails_gitlab ""
desc="issues on GitLab"]] and the [tails-dev@boum.org mailing list
archive](https://lists.autistici.org/list/tails-dev.html).
2. **[[Tell us on tails-dev@boum.org|about/contact#tails-dev]] about your plans** to make sure your
idea fits nicely into the [[big picture|contribute/design]], and
......@@ -158,8 +158,6 @@ You can also:
* subscribe to this website's RSS feed (see [[recentchanges]]);
* track the Git commits (using [[our Gitweb|contribute/git]]'s RSS
features);
* track [[review'n'merge
requests|contribute/working_together/Redmine#atom]].
## Build a Tails ISO
......
......@@ -10,7 +10,7 @@ feature.
Tasks that are currently stalled by the need for input have the
the `Research`, `Discuss`, or `Test` *Type of work* on our
[[!tails_redmine "" desc="TODO"]] list.
[[!tails_gitlab "" desc="TODO"]] list.
You probably want to start looking at the ones that are also in the
[[!tails_redmine_starter]] first so that you can gain confidence...
and we can smoothly learn to work together.
......
Tails issues are managed in a [[!tails_gitlab "" desc="GitLab"]].
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.
Some documentation about how we are using GitLab is available in the
[[contribute/working_together]] pages. See also the [[review and merge
process|contribute/merge_policy/review]] documentation.
Tinkering with GitLab issues is an important part of the
[[Ticket gardener|contribute/working_together/roles/ticket_gardener/]] role.
[[!toc levels=2]]
<a id="metadata"></a>
How we use GitLab metadata
==========================
On GitLab, issues and merge requests have metadata.
Being consistent in the use of GitLab metadata makes collective work
smoother. See [[document progress|contribute/working_together/document_progress]]
for more on this topic.
## 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.
## See also
See also the [GitLab doc on
issues](https://docs.gitlab.com/ce/user/project/issues/).
# Requesting input from someone else
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.
# Acting upon input requests
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.
Email interface
===============
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! :)
Tails tasks are managed in a [[!tails_redmine "" desc="Redmine project"]].
If you need to do something in Redmine and you appear to lack the
needed credentials, please ask [[tails-sysadmins@boum.org|about/contact#tails-sysadmins]] to give you
more power.
Some documentation about how we are using Redmine is available in the
[[contribute/working_together]] pages. See also the [[review and merge
process|contribute/merge_policy/review]] documentation.
Tinkering with Redmine is an important part of the
[[Ticket gardener|contribute/working_together/roles/ticket_gardener/]] role.
[[!toc levels=2]]
<a id="atom"></a>
Atom feeds
==========
Each custom query listed in the Redmine sidebar has an Atom feed.
Tracking review'n'merge requests
--------------------------------
Subscribe to:
* the [*Completed for the next release*](https://redmine.tails.boum.org/code/projects/tails/issues?query_id=327)
feed;
* the [*Needs Validation*](https://redmine.tails.boum.org/code/projects/tails/issues?query_id=117) feed;
* merge requests on [Salsa](https://salsa.debian.org/tails-team/tails/merge_requests/).
How to use Redmine's Atom feeds
-------------------------------
To use a Redmine Atom feed:
1. Go to the custom query you want to track.
2. Look for the *Atom* link at the bottom of the page.
3. Point your feed reader to that link.
Email commands
==============
This only works by sending mails from an email address associated with
a Redmine account.
For details, see the [corresponding documentation on the Redmine
website](https://www.redmine.org/projects/redmine/wiki/RedmineReceivingEmails#How-it-works).
Creating a ticket by email
------------------------
You need to provide all the required fields in the body of the email, and the
syntax is case sensitive. For example this works:
To: redmine@redmine.tails.boum.org
Subject: Test creating a ticket by email
Project: tails
Tracker: Feature
Status: Confirmed
Priority: Low
Type of work: Test
It should be possible to create a ticket by sending an email to Redmine.
If you send attachments with your email they will also be attached to the
ticket. For example your OpenPGP signature :)
Updating a ticket by email
--------------------------
An easy trick is to reply to an email notification about that ticket. Then only
include in the body of the email the fields that you want to change, and a
description for your changes. For example:
To: redmine@redmine.tails.boum.org
Subject: Re: [Tails - Feature #6813] (Confirmed) Test creating a ticket by email
Status: Resolved
This works but Redmine is quite picky on the syntax...
<a id="fields"></a>
How to use Redmine fields
=========================
It is important to be consistent in the use of the fields to make collective work
easier. See [[document progress|contribute/working_together/document_progress]]
for more on this topic.
Please take a time to see how we use the fields of Redmine:
* Subject:
- The Subject should be a short but clear description of what the ticket is about.
Some people are case sensitive, please try to consider that.
* Description:
- For the preferred style of this field when reporting a bug, refer to our
[[bug reporting instructions|doc/first_steps/bug_reporting]]. Features or
Discuss tickets may follow a different style.
* Status:
* New:
- New users' tickets are marked always as new. If a Tails contributor can
reproduce the issue, it should be marked as *Confirmed*.
- [[Help desk|contribute/working_together/roles/help_desk]] team is in
charge of keeping an eye on them.
* Confirmed:
- Tails contributors can reproduce the issue.
* In Progress:
- Some work towards resolution has been done.
- Added by Redmine automatically when a Git commit with `will-fix: #NNNN`
is added to the Tails repository. This keyword should be only used in
topic branches.
* Needs Validation
- Proposed changes are ready to be reviewed.
Read our [[merge policy|/contribute/merge_policy]] to know more.
* Resolved:
- Fixed in Git. The _Target version_ indicates whether it is fixed
in a version of Tails that was already released, or for a future one.
* Duplicate:
- Another ticket in Redmine covers this issue. Do not forget the related issue!
You can add a related issue from the 'Related issues' section on the ticket.
* Rejected:
- Not applicable, not a Tails problem, being worked on elsewhere.
* Priority
* Low:
- It would be good to have it, but nobody is volunteering to do it.
* Elevated:
- Regressions are always marked as Elevated.
* Assignee: assign yourself to a ticket if you are working on it to prevent duplicated
work.
* Category:
- This are usually transversal issues, not specific tools.
* Target version:
- The Tails release this ticket aims to be fixed for.
- If submitting code, the Tails release you would like your changes to be in.
* Feature Branch:
- Add the information of the branch for this issue in the format
`repositoryname:branch`, or only the branch name if it's on Tails repository.
* Type of work:
* Communicate:
- Inside or outside of Tails (for example, with other projects).
* Contributors documentation:
- Everything below /contribute on the website.
* Debian:
- Related or to be done on the Debian project.
* Discuss:
- Discuss tickets are reviewed to discuss during the monthly Tails
contributors meeting.
* End-user documentation:
- Everything below /doc on the website.
* Wait:
- Used when waiting for input from other projects.
* Website:
- All website work not covered by other options.
* Watchers:
- If you think somebody might be interested on this ticket although not as
assignee, you can add them as a watcher. They will receive an email with
information every time the ticket gets updated.
- If you create a ticket you will receive updates like a watcher.
- If you comment on a ticket, you're *not* automatically a watcher.
* Parent task:
- It is always good to add it if there is any. Sometimes we use this field to
organize work that spans over many tickets. See for example: [[!tails_ticket 7584]].
* Blueprint:
- Many times the work to fix the tickets is also done in a wiki page, see
<https://tails.boum.org/blueprint/>.
* Starter:
- Issues flagged as *Starter* on Redmine are a great tool for new contributors
getting into Tails. [[Learn
more|/contribute/working_together/criteria_for_starter_tasks/]].
# Requesting input from someone else
If you want to work on a ticket but you need some input from someone
else, ask your question on a comment on the ticket, mentioning them
with their Redmine login name: `@nick`. Redmine will send them
an email notification about it.
If you expect the person you're asking input from will need to do
substantial amounts of work to answer your question, you may file
a dedicated subtask assigned to them.
# Acting upon input requests
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 a ticket with `@nick`, you get an
email notification. You should ensure your email setup allows you to
notice such email from Redmine.
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 by creating a new subtask assigned to yourself, or using
whatever personal organization tools that work for you.
# Core team's work
Some of the teams who do
[[Core work|contribute/working_together/roles]] (be it paid or done on
a volunteer basis) maintain Redmine metadata in order to:
* provide visibility on what they doing & their priorities;
* give the Tails community some power over setting these priorities;
* allow 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.
In the [[!tails_redmine "" desc="Redmine"]] sidebar, you can see
a bunch of views 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! :)
Tails issues are now tracked in [[working_together/GitLab]].
......@@ -24,7 +24,7 @@ General
=======
- Not *Starter*:
- Has subtasks or is blocked by other issues.
- Is blocked by other issues.
- Needs to be split to be actionable.
Audit & Research
......