wiki/src/contribute/how/code.mdwn

   1 [[!meta title="Improve Tails source code"]]
   2
   3 <div id="intro">
   4
   5 <p>So you want to fix a bug or implement a new feature in Tails.
   6 Welcome aboard! Please read-on.</p>
   7
   8 [[!toc levels=2]]
   9
  10 </div>
  11
  12 # Foreword
  13
  14 ## Why should I read this page?
  15
  16 Every Free Software project is a bit different from the others. If you
  17 don't understand its development process, it is generally pretty hard
  18 for you to contribute in a way that is both efficient and joyful for
  19 you... and for its current core development team. This document is
  20 meant to help *you* understand what you need so that you can more
  21 efficiently and joyfully contribute to Tails.
  22
  23 ## Focus on low-effort maintainability
  24
  25 Many, many Live CD projects — including a few ones that aimed at
  26 enhancing their users' privacy — have lived fast and died young. We
  27 explain this by their being one wo/man efforts, as well as design
  28 decisions that made their maintenance much too costly timewise and
  29 energywise.
  30
  31 We want Tails to live as long as it is needed: Tails is not meant to
  32 be solely a pet project.
  33
  34 Since the early days of this project (i.e. early 2009), ease of
  35 maintenance in the long run has been a major factor in every decision
  36 we have made. Nowadays Tails is more alive and kicking than it has
  37 ever been, and we feel this would have been impossible without
  38  this kind of mindset.
  39
  40 Our focus on low-effort maintainability has practical consequences.
  41
  42 First of all, we tend to **carry the smallest possible delta** with
  43 our upstreams (i.e. upstream software, the Debian distribution, and
  44 the Debian Live build tools). Pretty important details about this can
  45 be found in our [[contribute/relationship_with_upstream]] statement
  46 rather than repeated here.
  47
  48 Second, we try **not to reinvent the wheel** too often, and flee the
  49 *Not-Invented-Here* syndrome like the plague. This implies very little
  50 code is actually written specifically for Tails: most of what we call
  51 *code work* on Tails is more similar to system administration than it
  52 is to programming: we mainly glue existing pieces together; when we
  53 happen to need a feature that no software provides yet, we tend to
  54 pick the best existing tool and do whatever is needed to get the
  55 needed feature upstream... which may, or may not, be writing a patch
  56 ourselves.
  57
  58 # How to get started
  59
  60 ## Pick up a task
  61
  62 This wiki is used as a basic bug tracking system: we use it to manage
  63 our todo and bugs lists as well as our [[!tails_roadmap]].
  64 If you already know which one of the listed tasks you want to fulfill
  65 and it *only* has the `todo/code` tag, you can probably safely skip to
  66 the next section.
  67
  68 So you want to contribute code to Tails but do not know where to
  69 start? Our [[!tails_redmine "" desc="TODO list"]] is huge and
  70 frightening, but...
  71
  72 *Do not panic!*
  73
  74 Let's see how we can help you picking up a task. A few tips:
  75
  76 * Choose something that matters for you, such as fixing that bug that
  77   annoys you so much or implementing this feature you are missing so
  78   much.
  79 * Choose something where your singular skills and knowledge are put to
  80   work.
  81 * Have a look to the [[!tails_redmine_easy desc="easy tasks"]] list: there is
  82   something, in each of these tasks, that one can do right away since
  83   it does not require deep knowledge of the Tails internals.
  84
  85 On the one hand, you may want to **start doing practical stuff
  86 immediately**. In this case, see on the [[!tails_redmine ""
  87 desc="TODO"]] list the tasks that have the `Code`
  88 *Type of work* set. You probably want to start looking
  89 at the few ones that are also in the [[!tails_redmine_easy desc="easy tasks"]] list
  90 first so that you can gain confidence and we can smoothly learn to
  91 work together.
  92
  93 On the other hand, you may prefer **picking up a task that requires
  94 some initial thought and discussion** before rushing to your
  95 `$EDITOR`. In this case, you probably want to look at the [[providing
  96 needed input guidelines|contribute/how/input]].
  97
  98 ## Get in touch with our past, present and future
  99
 100 So you know what bug you want to fix, what feature you want to
 101 implement.
 102
 103 Duplicated, unfinished or otherwise unusable work makes us sad, so
 104 unless you are sure it is really easy you should:
 105
 106 1. **Gather results of previous research and discussions.** Search
 107    this wiki and the [developers mailing-list
 108    archive](https://boum.org/mailman/pipermail/tails-dev) for previous
 109    discussions on the topic you are interested in; [[!tails_todo
 110    usb_install_and_upgrade desc="some"]] [[!tails_todo tasks
 111    macchanger desc="tasks"]] are much harder to get right than one
 112    could initially expect, and you'd better see how difficult it is to
 113    implement what you want.
 114 2. **[[Tell us|contribute/talk]] about your plans.** This helps making sure
 115    your idea fits nicely into the [[big picture|contribute/design]]
 116    and nobody is currently working on the same task.
 117
 118 # Hack
 119
 120 Tails is developed using a set of [[Git repositories|contribute/git]]. You
 121 probably want to base your work on the `devel` branch. If unsure, feel
 122 free to ask us.
 123
 124 Please think of how you will actually submit your work to us
 125 **before** you have changed 20 files for 10 different reasons ;) In
 126 other words, every commit shall implement one change and be labelled
 127 with a commit message that clearly expresses the rationale of your
 128 changes. This is needed so that we can review your work
 129 without too much difficulty: just explain every proposed change to us
 130 (almost) the same way as if you would explain it to anyone who lacks
 131 the background.
 132
 133 # Submit your work
 134
 135 Before diving into technical details please consider reading our
 136 (quite short) [[contribute/merge policy]].
 137
 138 You can submit small, easy changes as Git patches (prepared with the
 139 `git format-patch` command) over [[email|contribute/talk]].
 140
 141 For bigger, harder changes that will might require a few review/fix
 142 cycles before being merged in, it's better if you ask us to review and
 143 pull your work from a dedicated Git topic branch. If you already know
 144 where to host your personal repository in a public online place, this
 145 is great; or else you may want to [fork us on
 146 repo.or.cz](http://repo.or.cz/w/tails.git).
 147
 148 FIXME: mob branch on repo.or.cz? mob repository where anyone can
 149 create and push `feature/*` and `bugfix/*` branches?
 150
 151 # Want more?
 152
 153 ## Follow Tails development
 154
 155 Still here? Well, it seems you're not the
 156 *patch-in-a-hurry-and-then-forget* type.
 157
 158 Then you probably want to subscribe to the [tails-dev mailing
 159 list](https://boum.org/mailman/listinfo/tails-dev/). Maybe even
 160 subscribe to this website's RSS feed (see the [[recentchanges]] page)
 161 and/or track the Git commits (using [[our Gitweb|contribute/git]]'s RSS
 162 features). And probably read Tails [[specification and security design
 163 document|contribute/design]].
 164
 165 ## Building images
 166
 167 You probably want to test your changes before contributing them back;
 168 this may require you to [[build an ISO image|contribute/build]]. This step is
 169 also needed if you need to [[contribute/customize]] Tails.
 170
 171 # Talk to us
 172
 173 [[!inline pages="contribute/talk" raw="yes"]]