wiki/src/contribute/how/sysadmin.mdwn

   1 [[!meta title="Improve the infrastructure behind Tails"]]
   2
   3 <div id="intro">
   4
   5 <p>So you want to help improve the infrastructure behind Tails.<br />
   6 Welcome aboard! Please read-on.</p>
   7
   8 [[!toc levels=1]]
   9
  10 </div>
  11
  12 # Read this first
  13
  14 First of all, please read the [[goals and
  15 principles|contribute/working_together/roles/sysadmins#goals]] of the
  16 Tails system administration team.
  17
  18 # Skills needed
  19
  20 Essential skills for participating in the Tails infrastructure include
  21 basic Unix system administration knowledge and good
  22 communication skills.
  23
  24 Depending on the task, you may also need to be knowledgeable in either
  25 Debian system administration, scripting in Perl, Python, Ruby or shell,
  26 or one of the [[services we
  27 run|contribute/working_together/roles/sysadmins#services]].
  28
  29 <div class="note">
  30 <ul>
  31
  32 <li>To complete most tasks, some amount of Puppet work must be done.
  33 However, it is possible to participate without knowing Puppet, at
  34 least for your first contributions.</li>
  35
  36 <li>Being an expert beforehand is not required, as long as you are
  37 ready to learn whatever you need to know :)</li>
  38
  39 </ul>
  40 </div>
  41
  42 # How to choose a task
  43
  44 We use Redmine to manage our list of tasks:
  45
  46 * [tasks that require *Sysadmin*
  47   work](https://labs.riseup.net/code/projects/tails/issues?query_id=113)
  48 * [tasks that belong to the *Infrastructure*
  49   category](https://labs.riseup.net/code/projects/tails/issues?query_id=140)
  50
  51 Here are a few tips to pick a task:
  52
  53 * Focus on the issues marked as *[[Easy|easy_tasks]]* on Redmine.
  54 * Choose something that matters for you.
  55 * Choose something where your singular skills are put to work.
  56
  57 Do not hesitate to request our advice: tell us about your skills, and
  58 we will try to match it to a task.
  59
  60 If anything is unclear, ask us to specify the desired outcome in more
  61 details *before* you start working: this will save time to
  62 everybody involved.
  63
  64 <a id="hack"></a>
  65
  66 # How to implement and propose changes
  67
  68 Thanks to the [[tools we
  69 use|contribute/working_together/roles/sysadmins#tools]], you can
  70 contribute usefully without having an account on the actual systems.
  71
  72 ## If you don't know Puppet
  73
  74 A few tasks in Redmine can be fulfilled by testing something, and then
  75 reporting your results on the relevant ticket.
  76
  77 However, most tasks are a bit more complicated. Follow these steps to
  78 contribute useful bits, that someone else can then integrate into
  79 Puppet:
  80
  81 1. Prepare configuration, scripts and whatever is needed. During this
  82    process:
  83    * Write down every setup step needed to deploy the whole thing.
  84    * In particular, take note of any dependency you install.
  85      Better work in a minimal Debian stable system to avoid missing
  86      some (hint:  virtual machine, pbuilder chroot or alike).
  87    * Document how the whole thing is supposed to be used.
  88 1. Test, hack, test, [...]
  89 1. Publish your work somewhere, preferably in a Git repository to
  90    smooth any further iteration our first review pass may require.
  91    If you already know where to host your personal repositories, this
  92    is great; or else you may ask us to host your repository.
  93 1. Tell us what problem you tried to solve, and where we can find
  94    your solution.
  95
  96 ## If you know Puppet, or want to learn it
  97
  98 To solve a problem with Puppet, you need to:
  99
 100 * Either, improve a Puppet module. If we are not the original authors
 101   of this module, please contribute your changes upstream: we don't
 102   want to maintain forks forever.
 103 * Or, create a new Puppet module. But first, try to find an existing
 104   module that can be adapted to our needs.
 105
 106 Many Puppet modules can be found in the [shared Puppet
 107 modules](https://labs.riseup.net/code/projects/sharedpuppetmodules),
 108 the [Puppet Forge](https://forge.puppetlabs.com/), and on GitHub.
 109
 110 To smooth the reviewing and merging process: create atomic commits,
 111 document your changes in details, follow the Puppet [style
 112 guide](http://docs.puppetlabs.com/guides/style_guide.html), and
 113 carefully test your changes.
 114
 115 Once ready, you can submit trivial changes over email, in the form of
 116 Git patches prepared with `git-format-patch(1)`.
 117
 118 For anything more substantial, please publish your work as a Git topic
 119 branch. If you already know where to host your personal repositories,
 120 this is great; or else you may ask us to host your repository.
 121
 122 <a id="contact"></a>
 123
 124 # Contact information
 125
 126 Email us at <tails-sysadmins@boum.org>. We prefer receiving email
 127 encrypted with our OpenPGP key, that can be found on the keyservers,
 128 and is certified by the Tails signing key.