summaryrefslogtreecommitdiffstats
path: root/wiki/src/contribute/how/code.mdwn
blob: 8cd2411142251351a4832c9b9f7cdf76e82c16fb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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
[[!meta title="Improve Tails source code"]]

<div id="intro">

<p>Do you want to fix a bug or implement a new feature in Tails?
Welcome aboard, and please read on! If you want to quickly get up to
speed on how to write code for Tails you might want to look at our
[[Writing code for Tails|HACKING]] introduction first.</p>

[[!toc levels=2]]

</div>

# Foreword

Every Free Software project is a bit different from the others.
This page is meant to help you understand some basics of the Tails
project, so that you can more efficiently and joyfully contribute
to Tails.

## Focus on low-effort maintainability

Many, many Live system projects — including a few ones that aimed at
enhancing their users' privacy — have lived fast and died young. We
explain this by their being one wo/man efforts, as well as design
decisions that made their maintenance much too costly timewise and
energywise.

We want Tails to live as long as it is needed: Tails is not meant to
be solely a pet project.

Since the early days of this project (i.e. early 2009), ease of
maintenance in the long run has been a major factor in every decision
we have made. Nowadays Tails is more alive and kicking than it has
ever been, and we feel this would have been impossible without
this mindset.

Our focus on low-effort maintainability has practical consequences.

First of all, we tend to **carry the smallest possible delta** with
our upstreams (i.e. upstream software and Debian). For details about
this, read our [[contribute/relationship_with_upstream]] statement.
Moreover, we encourage you to improve Tails [[by working on
Debian|contribute/how/debian]] or
[[by working on GNOME|blueprint/GNOME_bugs_that_affect_Tails]].

Second, we try **not to reinvent the wheel**, and we flee the
[[!wikipedia Not_invented_here]] syndrome like the plague. Very little
code is actually written specifically for Tails: most of what we call
*code work* on Tails is more similar to system administration than it
is to programming. We glue existing pieces together. When we need
a feature that no software provides yet, we tend to pick the best
existing tool, and do whatever is needed to get the needed feature
upstream... which sometimes implies to write a patch ourselves.

# How to get started

## Pick up a task

We use [[!tails_redmine "" desc="Redmine"]] to manage
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
safely skip to the next section.

So you want to contribute code to Tails but do not know where to
start? Our coding [TODO
list](https://redmine.tails.boum.org/code/projects/tails/issues?query_id=119)
is huge and frightening, but...

*Do not panic!*

Let's see how we can help you picking up a task. A few tips:

* Choose something that matters for you, such as fixing that bug that
  annoys you so much or implementing this feature you are missing so
  much.
* Choose something where your singular skills and knowledge are put to
  work.
* Have a look to the [[!tails_redmine_starter]]: there is
  something, in each of these tasks, that one can do right away since
  it does not require deep knowledge of the Tails internals.

On the one hand, you may want to **start doing practical stuff
immediately**. In this case, see [list the tasks that have the `Code`
*Type of
work*](https://redmine.tails.boum.org/code/projects/tails/issues?query_id=119)
set. You probably want to start looking
at the few ones that are also in the [[!tails_redmine_starter]]
first so that you can gain confidence and we can smoothly learn to
work together.

On the other hand, you may prefer **picking up a task that requires
some initial thought and discussion** before rushing to your
`$EDITOR`. In this case, you probably want to look at the [[guidelines
for providing needed input|contribute/how/input]].

## Get in touch with our past, present and future

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
   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
   nobody is currently working on the same task.

# Hack

Tails is developed using a set of [[Git repositories|contribute/git]].
If unsure, base your work on the `devel` branch, or ask.

Every commit shall implement one change and be labeled with a commit
message that clearly expresses the rationale of your changes. This is
needed so that your work can be easily reviewed: explain every
proposed change to us in the same way you would explain it to someone
who would not get the background.

<a id="submit"></a>

# Submit your work

Before diving into technical details, please read our
[[contribute/merge policy]].

You can submit small, easy changes as Git patches (prepared with the
`git format-patch` command) over email to [[tails-dev@boum.org|about/contact#tails-dev]].

For larger changes that will certainly require a few review/fix cycles
before being merged, it's better if you push your work to a dedicated
Git topic branch, and [[ask us to review it|contribute/merge policy/submit]]. If you already know where
to host your personal repository in a public online place, this is
great; otherwise, you can [fork us on
GitLab](https://gitlab.com/Tails/tails), or ask the Tails system
administrators ([[tails-sysadmins@boum.org|about/contact#tails-sysadmins]]) to host your repository.

# Want more?

Still here? Good, please read on.

## Read about Tails design

The [[specification and design document|contribute/design]] will help
you understand better how Tails works.

## Follow Tails development

You should subscribe to the [[tails-dev mailing
list|about/contact#tails-dev]].

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

You should test your changes before contributing them back.
Most often, this requires you to [[build an ISO image|contribute/build]].

# Talk to us

You can subscribe to [[tails-dev@boum.org|about/contact#tails-dev]],
our development mailing list.