Development process

Tox and TokTok are software projects with very high security and stability requirements. It will potentially be used by hundreds of millions of people around the world. A security issue could have catastrophic consequences. Slightly less critical, but still very important, is stability. If the library underlying our chat clients is unstable, it’s annoying in the mildest case, and can be catastrophic to a single person (imagine the code arbitrarily deleting chat histories).

Therefore, toktok-team operates in a slightly different way from most open source projects. We have strict design and code review processes that no contributor, including the project owners, can violate. Github branch protection ensures that the review process is followed.

For any non-trivial development, we follow a rigorous design process. This process ensures that every decision is founded in reason and that at least some alternatives for the decisions have been considered. We split the design into two stages with a document accompanying each stage.

Goals, requirements, overview

The first stage is the design overview. This document contains the high level overview of a design. It starts by answering the following questions:

Next comes a list of requirements. For example:

The largest section of this document is the high level design overview. Here we describe, without going into implementation details, what components the solution will be comprised of, how they interact, and how they depend on each other. For tooling, this may include usage examples. For code, this won’t necessarily include API definitions. This part may discuss storage choices, protocol choices, and other high level design ideas.

Finally, the document includes a section discussing alternative approaches. The discussion gives a short description of a technology that solves a similar problem to ours, provides a link to the documentation of that technology, and points out reasons for not choosing it.

This document forms the basis for discussion, and we require at least one reviewer (if possible, two reviewers) to sign off on the idea. Ideally, we have many more people commenting and suggesting on the document.

You can use our design overview template or write your own. If you are unsure which direction you want to go in, writing small prototypes is a good way of exploring the space you are designing your project in. A prototype typically takes about a day to implement. If you take significantly more time, it will turn into a full implementation. Prototypes should be code you can throw away easily.

Detailed technical design

After going through several iterations of discussion and improvement, the rough design is expanded to become a full technical design. This is a separate document, which may initially be a copy of the above document. It specifies the APIs in detail, with message types, effects, and result types. These can be language-specific or language-agnostic such as web or RPC APIs. The evolution of this document usually goes hand in hand with the actual implementation.

Writing code

In many open source projects, the people with write access to the source code repository will submit code frequently and break things in the process. The breakage is then hopefully resolved. In contrast, toktok-team does not allow a single line of code (or documentation) to enter the master branch of the main repositories without being reviewed by at least one member that did not write the code. This means that even toktok-team members cannot push arbitrary unreviewed code to the repository.

If you want to contribute code or documentation, you will go through the normal Github process of forking the repository and opening a pull request. One or more reviewers from toktok-team will read and comment on your submission. You will most likely receive actionable feedback, which you can discuss on the review. You can then add more commits to the review by pushing them to the pull request branch.

A continuous integration system will build the code for all supported platforms and run an exhaustive testsuite on the x86_64 platform to increase confidence in the changes. We require close to 100% test coverage. The only exceptions are some cases of trivial generated code (Haskell deriving) and unreachable code caused by unavoidable weaknesses in the type system.

Requirements

Standards

We will hold ourselves and our contributors to high standards. Therefore, we require:

As always, every standard is subject to personal judgement, so if a rule does not make sense in a certain situation, you’re free to ignore it, so long as you’re able to justify your reasoning.

Repositories

We have three main repositories:

Stepwise howto for a contribution