wiki/src/contribute/how/code.mdwn

   1 [[!meta title="Improve Tails source code"]]
   2
   3 <div id="intro">
   4
   5 <p>Do you want to fix a bug or implement a new feature in Tails?
   6 Welcome aboard, and please read on! If you want to quickly get up to
   7 speed on how to write code for Tails you might want to look at our
   8 [[Writing code for Tails|HACKING]] introduction first.</p>
   9
  10 [[!toc levels=2]]
  11
  12 </div>
  13
  14 # Foreword
  15
  16 Every Free Software project is a bit different from the others.
  17 This page is meant to help you understand some basics of the Tails
  18 project, so that you can more efficiently and joyfully contribute
  19 to Tails.
  20
  21 ## Focus on low-effort maintainability
  22
  23 Many, many Live system projects — including a few ones that aimed at
  24 enhancing their users' privacy — have lived fast and died young. We
  25 explain this by their being one wo/man efforts, as well as design
  26 decisions that made their maintenance much too costly timewise and
  27 energywise.
  28
  29 We want Tails to live as long as it is needed: Tails is not meant to
  30 be solely a pet project.
  31
  32 Since the early days of this project (i.e. early 2009), ease of
  33 maintenance in the long run has been a major factor in every decision
  34 we have made. Nowadays Tails is more alive and kicking than it has
  35 ever been, and we feel this would have been impossible without
  36 this mindset.
  37
  38 Our focus on low-effort maintainability has practical consequences.
  39
  40 First of all, we tend to **carry the smallest possible delta** with
  41 our upstreams (i.e. upstream software and Debian). For details about
  42 this, read our [[contribute/relationship_with_upstream]] statement.
  43 Moreover, we encourage you to improve Tails [[by working on
  44 Debian|contribute/how/debian]] or
  45 [[by working on GNOME|blueprint/GNOME_bugs_that_affect_Tails]].
  46
  47 Second, we try **not to reinvent the wheel**, and we flee the
  48 [[!wikipedia Not_invented_here]] syndrome like the plague. Very little
  49 code is actually written specifically for Tails: most of what we call
  50 *code work* on Tails is more similar to system administration than it
  51 is to programming. We glue existing pieces together. When we need
  52 a feature that no software provides yet, we tend to pick the best
  53 existing tool, and do whatever is needed to get the needed feature
  54 upstream... which sometimes implies to write a patch ourselves.
  55
  56 # How to get started
  57
  58 ## Pick up a task
  59
  60 We use [[!tails_redmine "" desc="Redmine"]] to manage
  61 our lists of tasks and bugs, as well as our [[!tails_roadmap]].
  62 If you already know which one of the listed tasks you want to tackle
  63 and it has the *Code* Type of work, then you can probably
  64 safely skip to the next section.
  65
  66 So you want to contribute code to Tails but do not know where to
  67 start? Our coding [TODO
  68 list](https://redmine.tails.boum.org/code/projects/tails/issues?query_id=119)
  69 is huge and frightening, but...
  70
  71 *Do not panic!*
  72
  73 Let's see how we can help you picking up a task. A few tips:
  74
  75 * Choose something that matters for you, such as fixing that bug that
  76   annoys you so much or implementing this feature you are missing so
  77   much.
  78 * Choose something where your singular skills and knowledge are put to
  79   work.
  80 * Have a look to the [[!tails_redmine_starter]]: there is
  81   something, in each of these tasks, that one can do right away since
  82   it does not require deep knowledge of the Tails internals.
  83
  84 On the one hand, you may want to **start doing practical stuff
  85 immediately**. In this case, see [list the tasks that have the `Code`
  86 *Type of
  87 work*](https://redmine.tails.boum.org/code/projects/tails/issues?query_id=119)
  88 set. You probably want to start looking
  89 at the few ones that are also in the [[!tails_redmine_starter]]
  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 [[guidelines
  96 for providing needed input|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. At this point, we advise you to:
 102
 103 1. **Gather results of previous research and discussions** on the
 104    topic you are interested in. Search this website, [[!tails_redmine ""
 105    desc="tickets on Redmine"]] and the [tails-dev@boum.org mailing list
 106    archive](https://lists.autistici.org/list/tails-dev.html).
 107 2. **[[Tell us on tails-dev@boum.org|about/contact#tails-dev]] about your plans** to make sure your
 108    idea fits nicely into the [[big picture|contribute/design]], and
 109    nobody is currently working on the same task.
 110
 111 # Hack
 112
 113 Tails is developed using a set of [[Git repositories|contribute/git]].
 114 If unsure, base your work on the `devel` branch, or ask.
 115
 116 Every commit shall implement one change and be labeled with a commit
 117 message that clearly expresses the rationale of your changes. This is
 118 needed so that your work can be easily reviewed: explain every
 119 proposed change to us in the same way you would explain it to someone
 120 who would not get the background.
 121
 122 <a id="submit"></a>
 123
 124 # Submit your work
 125
 126 Before diving into technical details, please read our
 127 [[contribute/merge policy]].
 128
 129 You can submit small, easy changes as Git patches (prepared with the
 130 `git format-patch` command) over email to [[tails-dev@boum.org|about/contact#tails-dev]].
 131
 132 For larger changes that will certainly require a few review/fix cycles
 133 before being merged, it's better if you push your work to a dedicated
 134 Git topic branch, and [[ask us to review it|contribute/merge policy/submit]]. If you already know where
 135 to host your personal repository in a public online place, this is
 136 great; otherwise, you can [fork us on
 137 GitLab](https://gitlab.com/Tails/tails), or ask the Tails system
 138 administrators ([[tails-sysadmins@boum.org|about/contact#tails-sysadmins]]) to host your repository.
 139
 140 # Want more?
 141
 142 Still here? Good, please read on.
 143
 144 ## Read about Tails design
 145
 146 The [[specification and design document|contribute/design]] will help
 147 you understand better how Tails works.
 148
 149 ## Follow Tails development
 150
 151 You should subscribe to the [[tails-dev mailing
 152 list|about/contact#tails-dev]].
 153
 154 You can also:
 155
 156 * subscribe to this website's RSS feed (see [[recentchanges]]);
 157 * track the Git commits (using [[our Gitweb|contribute/git]]'s RSS
 158   features);
 159 * track [[review'n'merge
 160   requests|contribute/working_together/Redmine#atom]].
 161
 162 ## Build a Tails ISO
 163
 164 You should test your changes before contributing them back.
 165 Most often, this requires you to [[build an ISO image|contribute/build]].
 166
 167 # Talk to us
 168
 169 You can subscribe to [[tails-dev@boum.org|about/contact#tails-dev]],
 170 our development mailing list.