Development guidelines

Tempesta uses C, C++ and Python programming languages and all the code must obey the same coding style. We use the same coding style, slightly modified Linux kernel’s one to be applicable to C++, for both the C and C++ code. Python code must obey standard coding style described in PEP-8 document.

Don’t forget to check your code against common code smells before a commit.

Enable Git hooks:

git config --local core.hooksPath .githooks/

The coding style is automatically checked by scripts/checkpatch.pl, a slightly modified appropriate script from the Linux kernel, by a git hook on commit. Git commit fails even on warnings, but not all warnings are harmful, so the committing procedure is:

1. git commit -a
2. check all the warnings and errors printed by the script and fix them if necessary
3. if some warnings or errors don’t make sense use git commit -n -a to finally commit the changes

We don’t use standard Git branching workflow. Instead, we aim rapid features development and high reliability with release branches. There are 3 types of branches:

1. master – current development (HEAD) branch, relatively unstable. All new features (issues labeled as enhancement) are here. It can be considered as alpha version.
2. release (e.g. release-0.5.0) – quite stable branches. Only bugfixes (issues labeled as bug) are here. All bugs found in the branches get the crucial label and must be fixed ASAP.
3. development (named with a developer initials, the issue number and short description, e.g. ak-1377-h2-fixes) – a personal developer branches, which at some point are merged into master.

master and release branches are protected, so a pull request must pass code review and all CI tests before being merged into the branches.

Every feature or bug fix must be developed in designated developer’s branch. We name developer branches like ak-47 or ak-tdb where ak are initials of a developer and 47 or tdb is the issue number or name if it’s not in github issues yet. When the work is done a pull request from the branch is created and published for a review. At least 2 other developers must agree with the change. When the pull request is approved, the developer merges it into the master branch.

Our team members create their development branches in the main, Tempesta FW repo, not forks. This makes code review of developer pull requests easier since a reviewer don’t need to clone a new fork of the repo. Everyone (everyone in our team does code reviews) in our team don’t need to keep repo clones of everyone. Pull request (and branch) from a cloned repo is a good and only the option for an external contributor, not a team member.

Bug fixes from the master branch can be merged to release branches as well. Basically, bug fixes must be applied to all supported releases (not reached end of life (EoL) state).

Please pay attention to commit messages. When you submit a commit, imagine a developer (or yourself say in one year from now) resolving a problem with the code and trying to understand the reason for the change.

A commit message consists of a subject line, followed by an empty line, an optional body, and optional trailers.

• The subject must be capitalized, use the imperative mood, and be no longer than 72 characters.
• Leave one empty line between the subject and the body.
• Wrap all body lines at 72 characters.
• The body must explain why the change was made, not how it was implemented.
• An issue number is not a description and cannot replace a clear explanation of the fix. The commit message must describe the issue being fixed.
• If the commit is associated with an issue, you may reference its identifier using the Issue: trailer.
• If a commit is part of a multi-commit change, use the Part-of: trailer to group related commits under a shared feature or fix name.

Good:

Parse HTTP/2 frame headers correctly

Malformed frame headers can cause the parser to misread payload
boundaries, accept invalid lengths, and desynchronize the connection
state. When that happens, later frames may be interpreted against the
wrong stream or skipped entirely, making recovery impossible. This
change rejects invalid headers before they can affect subsequent reads.

Issue: #1234

Bad:

Parse HTTP/2 frame headers correctly

Fixes #1234 adding better parsing of frame headers

Bad:

The function `tfw_xyz()` should not set flag `ABC`

The first bad example doesn’t explain the changes, it only refers to the issue. The second bad example explains the implementation instead of the reason for the change.

When a feature is implemented as multiple commits that logically represent a single change, add the Part-of: trailer to each commit.

Example with two commits that fix a single HTTP/2 issue in steps:

Introduce stream-level flow control tracking for HTTP/2

HTTP/2 connections may stall when stream-level flow control state is
not tracked consistently across DATA frame processing. This change
adds the necessary bookkeeping to observe per-stream window usage,
but does not yet modify the behavior.

Part-of: http2-flow-control-stall-fix

Fix HTTP/2 connection stall caused by missing flow control updates

Previously, streams were not correctly updating flow control state
during DATA frame processing, causing the connection to stop reading
further frames. This change uses the previously introduced tracking
to correctly advance the window and restore normal flow.

Part-of: http2-flow-control-stall-fix

Tempesta uses Semantic versioning. If you prepare a pull request with some fixes to release branch, e.g. release-0.5.0, please update the minor version in TFW_VERSION in tempesta/tempesta_fw/tempesta_fw.h, e.g. update it from "0.5.0" to "0.5.1".

Your pull request may contain several patches (commits) and only one of them changes the version, so please put a new version tag to the accumulated change. Thus, in the branch release-0.5.0 we’ll have many tags for minor versions (patch levels): 0.5.1, 0.5.2 etc.

Unit and functional tests must be successfully executed by a developer before publishing a pull request for a review:

    $ cd tempesta && make test
    $ cd tempesta-test && ./run_tests.py

You can read more about functional tests in the README.

A developer must create a new test or an appropriate issue for the test for each bug fix, which wasn’t found by the testing system, or a new feature.

Continuous integration is closely linked with continuous testing, the subject of the section.

To avoid bottlenecks in the continuous delivery (CD) pipeline all the tests must be automated. The main difference between functional tests and CI tests is that origins can require complex environment setups (e.g. managing cluster nodes), longer time to run (e.g. tests for memory leaks) and powerful hardware (e.g. for performance testing).

We use two repositories for testing Tempesta FW – tempesta-test and tempesta so you should use the same branch names in these repositories if you create/modify/enable tests in tempesta-test for your tempesta branch.

1. Tempesta branch – branch from PR merged with master (or release-x.x.x branch);
2. Test branch – branch from PR (if this branch exists in Tempesta-test repo or master);
3. Stages:
   • kernel_build (optional);
   • Tempesta build;
   • Unit tests;
   • TLS tests;
   • python local tests;
   • python local tests with TCP segmentation 1;
   • python remote tests;
4. Link.

It jobs works for release branch. This job just use release-x.x.x test branch if PR is created for release Tempesta branch.

1. Tempesta branch – branch from PR (if this branch exists in Tempesta repo or master);
2. Test branch – branch from PR merged with master;
3. Stages:
   • kernel_build (optional);
   • Tempesta build;
   • python local tests;
   • python local tests with TCP segmentation 1;
   • python remote tests;
4. Link.

1. Tempesta branch – master;
2. Test branch – master;
3. Stages: as in (PR)Tempesta;
4. Link.

You can run tests on CI for various Tempesta and Tempesta-test branches. And also you can change tests params, MTU and remote/local setup. Link

See tempesta-ci repo for more info.

Each release (or GA), including minor versions (patch level) must be tagged, e.g.

    $ git tag
    0.5.0-pre7

Each release, e.g. 0.5.0, must have its own branch named by first two digits, e.g. 0.5. Bugfixes (i.e. versions 0.5.1, 0.5.2 etc.) must be fixated in the branches as tags.

Each release (e.g. 0.5 aka 0.5.0) and a patch of a release (e.g. 0.5.1) must be issued as a set of operating system packages.

Releases are issues in following steps:

1. all the issues from current milestone are closed.
2. the code is analyzed by Coverity scan and all the relevant reported code issues are fixed in context of a new, and the latest, issue in the milestone (please open a new issue by report of static analysis).
3. long running tests are successfully passed on the same platform with CI.
4. new packages are built for the current Linux kernel and Tempesta FW (Continuous delivery is described at the below).
5. new branch and tag are created for the release.

The master branch is assumed to provide new functionality to users on a continuous basis, while release branches provide stable versions ready for usage in production.

TBD it has sense to automate building of operating system packages (release automation) for real continuous delivery and easier implementation of continuous deployment of a user side. Currently we have scripts for packages building, but the process is still manual. The packages must be automatically tested in VMs. This is the subject for Continuous delivery (#786) issue.

Users can setup their package managers, e.g. apt or dnf, to pull the pre-built packages from our servers.

This Wiki is updated by the code developers. Please use this template when you update the wiki:

Syntax:         cache <mode>;
Default:        cache 2;
Context:        global
Reconfig:       false
Repeat:         false

There should be additional information about the directive here. Add configuration examples for common presets or common use cases for every directive. Especially implicit directives.

This is real example for cache directive. Here:

• Syntax – description of the directive syntax;
• Default – value by default. This should be disabled if directive disabled by default;
• Context – specify the scope for every directive. E.g. cache_bypass may be listed out of any directive blocks, inside vhost block and inside location block;
• Reconfig – true | false. Specify whether this directive is on-the-fly configuration;
• Repeat – true | false. Specify whether this directive can be used multiple times;

You can edit the wiki using the GitHub web interface or work with it as any other repo clonning it from git@github.com:tempesta-tech/tempesta.wiki.git

We maintain the Wiki in a GitHub repository, so a GitHub Flavored Markdown extension (a.k.a. GFM)is used.

Please after commit check how the changes look on the website wiki. The website wiki is generated by the Pythom library Marko GFM and rendered with Prism. E.g. note that it has more restricted set of supported languages for code snippets. Couple of rules to follow:

• the website wiki has it’s own headers, so the top header in the wiki is ##, not #
• to make a link to a wiki page from another one, use the page name, without any slashes or domain. E.g. [PURGE](Caching-Responses) is correctly displayed on the GitHub and website wikis, while [PURGE](/Caching-Responses) or [PURGE](https://github.com/tempesta-tech/tempesta/wiki/Caching-Responses) are broken.

If changes made to code left place for further improvements, ‘to do’ mark should be left in code in format:

/* TODO #3456: Short description of planned improvements */

For the improvement should be created issue and its number should be referred in the TODO comment along with short description of it. Please do not use FIXME for that purpose, so it can be left for private use in drafts by developers.

1. Continuous Integration by Martin Fowler.
2. Continuous integration essentials by Codeship.
3. A successful Git branching model.