New contributors can get started with the how to contribute code to Tails documentation.
Tails is developed in a set of Git repositories.
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.
See our documentation guidelines.
Verify that your changes do not affect the rest of the user documentation and FAQ. If so, fix it in your development branch so that it gets automatically integrated when your branch get released.
Regarding the FAQ, don't write new questions in advance but make sure that the existing ones are still correct.
A branch proposed for review and merge must have been tested when applied against the target branch(es) of the requested merge.
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
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 on email@example.com so that the author knows
s/he needs to fix his/her stuff before reapplying it at a later point.
All development should happen in topic branches. For a new feature XXX, it should
feature/XXX. For a bugfix about YYY, it should be named
bugfix/YYY. Ideally, include the relevant ticket number in the topic
branch name, e.g.
When the developer thinks it is good enough and has tested it, she must:
- if you have access to our Jenkins instance (if you don't know what this means, you do not) please make sure that your branch has not broken any tests!
- set the ticket's Status field to In Progress
- set the ticket's QA Check field to Ready for QA
- assign this ticket to nobody (aka. unassign it from yourself) by default. Unless it's clear to you that the current release manager won't be able or willing to do this specific review; in that case, you shall try to find someone else to do the review, and assign the ticket to them.
- set the ticket's Feature Branch field
- set the ticket's Target version field to the release you would like your changes to be in
- for important changes, if you feel the need to ask input from the greater development community, notify the firstname.lastname@example.org mailing list
Then, if the reviewer asks for more development to be done before merging, they should set the ticket's QA Check field back to Needs more dev or Needs more info state, and from now on it's the responsibility of the branch/ticket "holder" to change it back to Ready for QA once they consider the issues raised by the reviewer are fixed.
- When you start doing a review'n'merge, assign the relevant ticket to you, in order to avoid duplicated work.
- Merge the base branch (the one you're supposed to merge the reviewed
topic branch into, as specified in
config/base_branchand in the pull request -- they must match) into the topic branch.
- Build the topic branch and test the feature.
- Check automated ISO build and test results on https://jenkins.tails.boum.org/.
- Check the diff e.g. with
git log -p. Beware of changes introduced by merge commits: either add the
git log, or use
git diffafter reviewing the individual patches.
- Check the APT suite with
ssh email@example.com reprepro list [bugfix|feature]-<name-with-dashes>
- Check the user and design documentation.
- Check the ticket.
- 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.
- Remember that it's hard to receive negative feedback. Don't forget to note the good parts, be constructive and precise in your comments, and never use reviews to make personal attacks. You can read these blog posts on review and feedback:
Merge the branch with
- for a new feature: into
- for a fix on top on the last RC: into
testing; then merge
- for a fix on top of the last stable: into
stable; then merge
Please consider including
fix-committed: #NNNN in the commit
message, NNNN being the ticket number that is fixed by the branch
you are merging. Then, Redmine will automatically flag the
corresponding ticket as "Fix committed" once you push the results of
your merge to our main Git repository. For example:
Merge branch 'bugfix/8470-clean-up-apt-pinning' (Fix-committed: #8470)
- Update the QA Check field on the ticket. If there is no remaining
tasks listed on the ticket, then change its status to Fix
committed (unless you used the
fix-committedkeyword documented above); else, ask the branch submitter to split the remaining tasks into other tickets.
- Push the updated branch to the master Git repository.
- Reply to the email that requested the review, if any.