Commit c8b7ca47 authored by Tails developers's avatar Tails developers

Fully rework the website "how to contribute" section.

parent 8644e307
[[!meta title="Building a Tails image"]]
[[!toc levels=2]]
One may want to [[customize]] her image before building.
Every following command must be run as `root`, at the root of the
source directory one has [[downloaded|download]].
source directory one has [[downloaded|Git]].
For the impatient ones:
$ git clone git://git.immerda.ch/amnesia.git
$ cd amnesia
$ sudo su
# lb config
# lb build
# lb config && lb build
Dependencies
============
......
[[!meta title="Contribute"]]
[[!meta title="Contributing to Tails"]]
<div id="page-contribute">
<div id="intro">
<p>
There are many ways to contribute to Tails: you can write
specifications or documentation, describe your usecases, translate
this website into your native language, [[setup a BitTorrent or HTTP
mirror|contribute/mirror]]. Read on!
There are many ways <strong>you</strong> can contribute to Tails:
<ul>
<li>[[Setup a BitTorrent or HTTP mirror|contribute/how/mirror]]</li>
<li>[[Help other Tails users|contribute/how/help]]</li>
<li>[[Improve documentation|contribute/how/documentation]]</li>
<li>[[Report a bug|contribute/how/report_a_bug]]</li>
<li>[[Fix a bug|contribute/how/code]]</li>
<li>[[Implement a new feature|contribute/how/code]]</li>
<li>[[Translate text into your native language|contribute/how/translate]]</li>
<li>[[Provide needed input to developers|contribute/how/input]]</li>
</ul>
</p>
</div> <!-- #intro-->
<div class="container">
<div id="tools">
<div id="design">
<h1>Tools</h1>
<h1>Design</h1>
<p>This wiki is used as a basic bug tracking system:</p>
<p>Tails has a [[specification and design
document|contribute/design]].</p>
<ul>
<li>[[/bugs]]</li>
<li>[[/TODO]]</li>
<li>[[/wishlist]]</li>
<li>[[patches|/patch]]</li>
</ul>
<p>Other design documentation:</p>
The tags assigned to these TODO items
(e.g. todo/translate, todo/research) will hopefully help you
find a way to participate.
[[!map pages="contribute/design/*"]]
</div> <!-- #tools -->
</div> <!-- #design -->
<div id="other">
......@@ -44,7 +47,7 @@ mirror|contribute/mirror]]. Read on!
<li><a href="http://bugs.debian.org/cgi-bin/[email protected]">bugs that we are interested in on the Debian BTS</a></li>
</ul>
[[!map pages="contribute/*"]]
[[!map pages="contribute/* and !contribute/design and !contribute/design/* and !contribute/how and !contribute/how/*"]]
</div> <!-- #other -->
......@@ -52,39 +55,31 @@ mirror|contribute/mirror]]. Read on!
<div class="container">
<div id="source">
<div id="tools">
<h1>Tools</h1>
<h1>Source code</h1>
<p>You can [[fetch Tails source code using git|git]].</p>
<p>You can fetch the source code:</p>
<p>This wiki is used as a basic bug tracking system:</p>
<ul>
<li>as a [[tarball]];</li>
<li>using [[git]].</li>
<li>[[/bugs]]</li>
<li>[[/TODO]]</li>
<li>[[/wishlist]]</li>
<li>[[patches|/patch]]</li>
</ul>
</div> <!-- #source -->
<div id="build">
<h1>Building images</h1>
<p>
Before contributing your changes back, You probably want to test your
changes before contributing them back; this may require you to [[build an ISO
image|build]]. This step is also needed if you need to [[customize]] Tails.
</p>
</div> <!-- #build -->
</div> <!-- .container -->
</div> <!-- #tools -->
<div id="talk">
<h1>Talk</h1>
<h1>Talk with us</h1>
[[!inline pages="talk-dev" raw="yes"]]
</div> <!-- #talk -->
</div> <!-- .container -->
</div> <!-- #page-contribute -->
[[!meta redir=contribute]]
See the [[development section|/contribute]] of this website.
[[!meta title="Improve Tails source code"]]
<div id="intro">
<p>So you want to fix a bug or implement a new feature in Tails.
Welcome aboard! Please read-on.</p>
[[!toc levels=2]]
</div>
# Forewords
## Why should I read this page?
Every Free Software project's development process is a bit different
from the others. If you don't understand its development process, it
is generally pretty hard for you to contribute in a way that is both
efficient and joyful for you... and for its current core development
team. This document is meant to help *you* understand what you need so
that you can more efficiently and joyfully contribute to Tails.
## Focus on low-effort maintainability
Many, many Live CD projects — including a few privacy-targeted ones —
have lived fast and died young. We explain this on the one hand by
their being one wo/man efforts, on the other hand by design decisions
that made their maintenance too much costly timewise and energywise.
We want Tails to live as long as it is needed: Tails is not meant to
solely be a pet project.
Since the early days of this project (i.e. early 2009), ease of
maintenance on the long run has been a major factor in any 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 kind of 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, the Debian distribution, and
the Debian Live build tools). Pretty important details about this can
be found in our [[contribute/relationship_with_upstream]] statement
rather than repeated here.
Second, we try **not to reinvent the wheel** too often, and flea the
*Not Invented Here* syndrome like the pest. This implies very few 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 mainly glue existing pieces together; when we
happen to need a feature that no software provides yet, we tend to
choose the best among existing tools and do whatever is needed to get
the needed feature upstream... which may, or may not, be writing a
patch ourselves.
# How to get started
## Pick up a task
This wiki is used as a basic bug tracking system: we use it to manage
our [[todo]] and [[bugs]] lists as well as our [[contribute/roadmap]].
If you already know which one of the listed tasks you want to fulfill
*and it is only tagged `todo/code`*, you can probably safely skip to
the next section.
So you want to contribute code to Tails but do not know where to start
with. Our TODO list 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
hard.
* Choose something where your singular skills and knowledge are put to
work.
* Have a look to the [[easy tasks|todo/easy]] list: 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 the tasks tagged `todo/code` on the
[[/TODO]] list. You probably want to start looking at the few ones
that are also in the [[easy tasks|todo/easy]] list 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 [[providing
needed input|contribute/how/input]] guidelines.
## Get in touch with our past, present and future
So you know what bug you want to fix, what feature you want to
implement.
Duplicated, unfinished or otherwise unusable work makes us sad, so
unless you are sure it is really trivial you should:
1. **Gather results of previous research and discussions.** Search
this wiki and the [developers mailing-list
archive](https://boum.org/mailman/pipermail/tails-dev) for previous
discussions on the topic you are interested in;
[[some|todo/macchanger]] [[tasks|todo/usb_install_and_upgrade]] are
much harder to get right than one could initially expect, and you'd
better get you a taste of how hard what you want to implement
really is.
2. **[[Tell us|talk-dev]] about your plans.** This helps making 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|git]]. You
probably want to base your work on the `devel` branch. If unsure, feel
free to ask us.
Please think of how you will actually submit your work to us
**before** you have changed 20 files for 10 different reasons ;) In
other words, every commit shall implement one change and be labelled
with a commit message that clearly expresses the rationale of your
changes. This is needed so that we are able to review your work
without too much pain: just explain every proposed change to us
(almost) the same way as if you would explain it to anyone who lacks
the background.
# Submit your work
Before diving into technical details please consider reading our
(quite short) [[contribute/merge policy]].
You can submit small, easy changes as Git patches (prepared with the
`git format-patch` command) over [[email|talk-dev]] or post on the
[[patches page|patch]].
For bigger, harder changes that will might require a few review/fix
cycles before being merged in, it's better if you ask us to review and
pull your work from a dedicated Git topic branch. If you already know
where to host your personal repository in a public online place, this
is great; else you may want to [fork us on
repo.or.cz](http://repo.or.cz/w/tails.git).
FIXME: mob branch on repo.or.cz? mob repository where anyone can
create and push `feature/*` and `bugfix/*` branches?
# Want more?
## Follow Tails development
Still here? Well, it seems you're not of the patch-in-a-hurry'n'forget
kind.
You probably want to subscribe to the [tails-dev mailing
list](https://boum.org/mailman/listinfo/tails-dev/) then. Maybe even
subscribe to this website's RSS feed (see the [[recentchanges]] page)
and/or track the Git commits (using [[our Gitweb|git]]'s RSS
features). And probably read Tails [[specification and security design
document|contribute/design]].
## Building images
You probably want to test your changes before contributing them back;
this may require you to [[build an ISO image|build]]. This step is
also needed if you need to [[customize]] Tails.
# Talk to us
[[!inline pages="talk-dev" raw="yes"]]
[[!meta title="Improve Tails documentation"]]
<div id="intro">
<p>Tails documentation would greatly benefit from your help.</p>
[[!toc levels=1]]
</div>
# Reporting errors
We do value documentation very much, but it's difficult to keep it
up-to-date. If you find a typo or an error in the documentation please
do let us know — ideally, by submitting a patch with your fix.
# Writing
The easiest documentation tasks may be found by looking at the items
tagged `todo/documentation` on the [[/TODO]] list. Small fixes and
enhancements are greatly welcome, and can be done directly in this
wiki's web interface, by [[sending us|talk-dev]] Git patches, or by
publishing a [[Git]] branch.
But there is more: Tails [[end-user documentation|support]] needs lots
of work. A plan for end-user documentation reorganization was thought
through and sent to the [Tails development
mailing-list](https://boum.org/mailman/listinfo/tails-dev/) on Thu, 17
Feb 2011. Documentation writers coordinate themselves using our usual
[[development communication channels|talk-dev]]. On the technical
side, a dedicated `doc-rework` [[Git]] branch has been setup to host
this work.
# Translating
We want Tails [[end-user documentation|support]] to be translated in
as many languages as possible. See the [[guidelines for
translators|contribute/how/translate]] for details.
# Talk to us
[[!inline pages="talk-dev" raw="yes"]]
[[!meta title="Help other Tails users"]]
Hanging our on [[our IRC channel|talk-dev]] and providing assistance
to new users is incredibly valuable.
[[!meta title="Provide needed input to developers"]]
Some Tails planned features require initial tests, thought and/or
discussion before actual implementation work can start. You may want
to contribute to this effort.
*Do not panic!* Some of this preparation work can be done by people
who lack the technical skills needed to actually implement the desired
feature.
Tasks that are currently blocked by the need for input are listed in
the *Research*, *Discuss* and *Test* sections of the [[/TODO]] list.
You probably want to start looking at the ones that are also in the
[[easy tasks list|todo/easy]] first so that you can gain confidence...
and we can smoothly learn to work together.
# Talk to us
[[!inline pages="talk-dev" raw="yes"]]
[[!meta title="Setup a Tails mirror"]]
Setting up a Tails mirror can help Tails users downloading it faster
and more reliably.
<div id="intro">
<p>Setting up a Tails BitTorrent or HTTP mirror may help Tails users
downloading it faster and more reliably.</p>
[[!toc levels=2]]
</div>
BitTorrent
==========
......
[[!meta title="How to report a Tails bug"]]
The [[bugs page|/bugs]] has detailed instructions to report a bug you
have found in Tails.
[[!meta title="Improve Tails for your language speakers"]]
<div id="intro">
<p>So you want to make it easier to use Tails for your language
speakers. Welcome aboard! Please read-on.</p>
[[!toc levels=3]]
</div>
# Things to translate
## Custom programs
Tails ships with several custom programs that need to be translated.
The (gettext) PO files are in [[!tails_devel_gitweb_dir
config/chroot_local-includes/usr/share/locale]].
## Website and documentation
The [[end-user documentation|support]] is being reorganized, please
coordinate with documentation writers before translating content that
may, or may not, evolve quickly: see [[contribute/how/documentation]].
## Other strings
See the *Translate* section of the [[/TODO]] list.
# Translation tools
## Web interface
Using the web interface (*Improve translation* button) is nice for
quick tasks such as un-fuzzying a recently changed string or fixing a
typo; on the other hand, most translators find it painful and
error-prone for more serious translation work.
Moreover, parts of Tails (most notably our custom programs) cannot be
translated using the web interface. We therefore recommend anyone
willing to seriously get involved into Tails translation work to use
more appropriate tools, such as a real PO file editor; see bellow for
details.
## PO editor
The [Poedit](http://poedit.sourceforge.net/) editor is installed in
Tails.
Many different workflows could be used to translate Tails strings
using a PO editor. Let's describe a few recommended ones, from the
smallest to the biggest initial setup time... the last ones actually
being the most comfortable to work with on the long run.
### Piggy-back the web interface
1. In the web interface, click the *Improve translation* button on the
page you wish to translate.
2. In the text edition web page, copy the whole text.
3. Paste it into a new, empty raw text document.
4. Save this text document as a file whose name ends with the `.po`
extension.
5. Open the `.po` file in your preferred PO file editor.
6. Translate whatever you can.
7. Paste back the whole resulting text into your web browser.
8. Preview your changes.
9. Click *Save* when satisfied with the results.
### Using Git
You can either send us Git patches or ask us to pull from your Git
branch.
Note that the website shall be translated in the `master` branch,
while custom Tails programs live in the `devel` branch.
#### Send us Git patches
1. Clone Tails [[Git repository|git]] onto your local system.
2. Translate whatever you can in your preferred PO file editor.
3. Commit the changes you made to `.po` files.
4. Use the `git format-patch` command to prepare patches.
5. [[Send us|talk-dev]] your patches.
6. Frequently merge changes from our main repository into yours.
#### Ask us to pull from your Git branch
1. Setup [[Git repository|git]]: if you already know where to host
your personal Git repository in a public place, this is great; else
[fork us on repo.or.cz](http://repo.or.cz/w/tails.git).
2. Translate whatever you can in your preferred PO file editor.
3. Commit the changes you made to `.po` files.
4. Push your changes to your online Git repository.
5. [[Ask us|talk-dev]] to pull from the branch(es) you worked on.
6. Frequently merge changes from our main repository into yours.
# Supported languages
Only a few languages are currently somehow supported in Tails, namely:
Arabic, Chinese, English, French, Italian, German, Portuguese, Russian
and Spanish (Castellano).
Support for only a subset of these languages is enabled on this
website.
Adding support for your preferred language is possible, but beware:
* our website text evolves relatively quickly;
* useful translations are no one-shot job and need to be maintained on
the long run, which may take roughly two hours a month.
As a conclusion, forming a translators team dedicated to your
language's support in Tails might be useful to make the maintenance
work happier and more sustainable.
# Talk to us
[[!inline pages="talk-dev" raw="yes"]]
[[!meta title="Git merge policy"]]
<div id="intro">
<p>New contributors can get started with the [[how to contribute code
to Tails|contribute/how/code]] documentation.</p>
<p>Tails is developed in a set of [[Git repositories|git]]. Slightly
different merge policies apply to contributors depending on their
involvement level. On the other hand, some rules apply to anyone. This
page documents both.</p>
[[!toc levels=2]]
</div>
# Common rules
[[!inline pages="contribute/merge_policy/common_rules" raw=yes]]
# Newcomer / patch'n'forget contributor
[[!inline pages="contribute/merge_policy/newcomer" raw=yes]]
# Core developer
[[!inline pages="contribute/merge_policy/coredev" raw=yes]]
[[!meta title="Git merge policy: common rules"]]
## Documentation is not optional
When writing Tails code, one commits to adapt the design and end-user
documentations accordingly in a timely manner, writing brand new
chapters if needed.
As a side note, best is generally to write specification and design
documentation before implementing changes; among other very valid
reasons to do so, it may avoid doing work that won't be applied ever,
or be reverted later, because of a faulty design that was reviewed and
diagnosed only when the implementation was up and running. On the
other hand, we're not great fans of over-engineering and we do know
proceeding like this is not always an option, as the right design
sometimes arises from erratic implementation attempts.
## Do not break the build... or get reverted
Noone should ever push changes breaking the build into the shared Git
repository. On the other hand, this may happen since preliminary,
untested changes may in some circumstances land into our `devel`
branch to be reviewed and get more exposure.
If you find the `devel` branch in a non-building state and can
identify the root cause of it to a recent commit, fix it if you wish,
but don't let it disturb you otherwise: just revert the faulty commit
and [[inform the other developers|talk-dev]] so that the author knows
s/he needs to fix his/her stuff before reapplying it at a later point.
[[!meta title="Git merge policy: core developer"]]
## No unfinished stuff rotting for too long in the `devel` branch
A core developer who is commited to work on Tails on the long run may
carefully decide to merge work-in-progress code into the `devel`
branch, in order to get early feedback and testing results from
others.
When doing this, one commits to bring such "technology preview"
changes up to release quality in a timely manner. Unfinished code is
subject to reverting next time we decide to merge the `devel` branch
into the `testing` one and freeze it to prepare a release.
A development workflow based on topic-branches guarantees against such
hazards; moreover it helps linking together the various commits that
are part of a given patchset that can therefore be easily reviewed as
a whole, rather than as spread out individual commits.
[[!meta title="Git merge policy: newcomer / patch'n'forget contributor"]]
## Pull once in *good enough* state
Changes proposed by new contributors, or by the patch'n'forget kind,
shall respectively be applied once they are in *good enough* state.
That is, once the core developers team feels like maintaining it on
the long run in case the initial submitter disappears. Such
maintenance includes: polishing the proposed changes to make them fit
for release; writing and updating the design and end-user
documentations; fixing bugs.
......@@ -16,7 +16,7 @@ Every ISO image we ship is a hybrid one:
<p>
Any help to spread Tails is more than welcome,
[[using BitTorrent or by setting up a web mirror|contribute/mirror]].
[[using BitTorrent or by setting up a web mirror|contribute/how/mirror]].
</p>
<p>
......
......@@ -97,3 +97,6 @@ speak every language in the world. If you find issues using one of the
supposedly supported languages, don't hesitate to [[tell us about
it|found_a_problem]]. E.g. Tails probably lacks some non-Latin fonts
or input systems.
If you wish to make it easier to use Tails for your language speakers,
see the [[translators guidelines|contribute/how/translate]].
The Amnesic Incognito Live System and this documentation wiki are
developed in a bunch of Git repositories.
[[!meta title="Git repositories"]]
<div id="intro">
<p>The Amnesic Incognito Live System and this documentation wiki are
developed in a bunch of Git repositories.</p>
<p><strong>Related pages</strong></p>
<ul>
<li>[[contribute/merge_policy]]</li>
</ul>
<p><strong>Table of contents</strong></p>
[[!toc levels=2]]
</div>
Main repository
===============
......
......@@ -120,7 +120,9 @@ span.title {
#page-support #doc, #page-support #found_a_problem,
#page-about #warning, #page-about #license,
#page-found_a_problem #bugs, #page-found_a_problem #wishlist,
#page-contribute #source, #page-contribute #build, #page-contribute #tools, #page-contribute #other,
#page-contribute #source, #page-contribute #build, #page-contribute #tools,
#page-contribute #design, #page-contribute #other,
#page-contribute #talk,
#page-download #bittorrent, #page-download #http {
display: inline-block;
width: 35%;
......@@ -132,6 +134,7 @@ span.title {
#page-about #warning,
#page-found_a_problem #bugs,
#page-contribute #source, #page-contribute #tools,
#page-contribute #design,
#page-download #bittorrent
{
margin-right: 2em;
......
......@@ -82,6 +82,9 @@ ikiwiki will include your shortcut in the standard underlay.
* [[!shortcut name=tails_website url="https://tails.boum.org/%s"]]
* [[!shortcut name=tails_gitweb url="http://git.immerda.ch/?p=amnesia.git;a=blob_plain;f=%s"]]
* [[!shortcut name=tails_devel_gitweb url="http://git.immerda.ch/?p=amnesia.git;hb=refs/heads/devel;a=blob_plain;f=%s"]]
* [[!shortcut name=tails_gitweb_dir url="http://git.immerda.ch/?p=amnesia.git;a=tree;f=%s"]]
* [[!shortcut name=tails_devel_gitweb_dir url="http://git.immerda.ch/?p=amnesia.git;hb=refs/heads/devel;a=tree;f=%s"]]
* [[!shortcut name=tails_live-boot_gitweb url="http://git.immerda.ch/?p=tails_live-boot.git;a=blob_plain;f=%s"]]
* [[!shortcut name=tails_live-config_gitweb url="http://git.immerda.ch/?p=tails_live-config.git;a=blob_plain;f=%s"]]
* [[!shortcut name=launchpad_bug url="https://bugs.launchpad.net/onboard/+bug/%s" desc="Launchpad bug #%s"]]
......
If you want to talk publicly to Tails developpers or users:
[[!meta title="Talking in public with other Tails developers and users"]]