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.

Design documentation

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.

User documentation

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.

Test your code

A branch proposed for review and merge must have been tested when applied against either experimental, or against the target branch(es) of the requested merge.

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 so that the author knows s/he needs to fix his/her stuff before reapplying it at a later point.

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.

Core developer

All development should happen in topic branches. For a new feature XXX, it should be named feature/XXX. For a bugfix about YYY, it should be name bugfix/YYY. When the developer thinks it is good enough and has tested it, she must:

• merge the topic branch into the experimental one
• set the ticket's QA Check field to Ready for QA
• 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
• ask the Release Managers to review and merge (in devel generally, in testing or stable for bugfixes) by writing to the tails-dev@boum.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.

Review and merge process

Review

• Build the branch (or experimental) and test the feature.
• Check the diff e.g. with git log -p.
• Check the APT suite with ssh reprepro@incoming.deb.tails.boum.org reprepro list [bugfix|feature]-<name-with-dashes>
• Check the user and design documentation.
• Check the ticket.

Merge

On the Git side, merge the branch with --no-ff :

• for a new feature: into devel
• for a fix on top on the last RC: into testing and devel
• for a fix on top of the last stable: into stable and devel

On the APT repository side, merge the suites.

Book keeping

1. 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; else, ask the branch submitter to split the remaining tasks into other tickets.
2. Push the updated branch to the master Git repository.
3. If you merged into a branch that is built by our Jenkins, also push it to the Git repository on lizard (gitolite@git.puppet.tails.boum.org:tails).
4. Reply to the email that requested the review.