The Varnish Developers Guide

This is the deliberately short and to the point list of things Varnish Developers should know.

Behaviour

  • Be sensible.

  • If in doubt, think.

  • If still in doubt, ask.

  • Admit your mistakes, it’s faster that way.

  • Thou SHALL not paint bikesheds.

  • We will toss you out of the project rather than add another rule.

Technical stuff

  • Our coding style guideline is FreeBSD’s style(9)

  • See autogen.des script for developer options to the toolchain.

  • We always -Werror, there are no harmless warnings, only source code that does not express intent well enough.

  • We prefer the source code, rather than the comments explain what is going on, that way tools like FlexeLint and Coverity also gets a chance.

  • Our reference platforms are Ubuntu and FreeBSD.

  • Asserts have negative cost, they save developer time next time around.

  • Our license is BSD 2-clause or looser, no GPL or LGPL.

  • It took 11 years for the first major security issue, and that was too soon.

Bugs, issues, feature requests & VIPs

Bugs, issues and feature requests start out as github issues.

Monday at 13:00-14:00 (EU time) we “bug-wash” on IRC to decide who and how issues are dealt with.

Issues we cannot do anything about are closed.

If feature-requests make sense, they get moved to a wiki/VIP page until somebody implements them.

Varnishtest cases for bugs is the norm, not the exception.

Architectural stuff

These rules are imported from the X11 project:

  • It is as important to decide what a system is not as to decide what it is.

  • Do not serve all the world’s needs; rather, make the system extensible so that additional needs can be met in an upwardly compatible fashion.

  • The only thing worse than generalizing from one example is generalizing from no examples at all.

  • If a problem is not completely understood, it is probably best to provide no solution at all.

  • If you can get 90 percent of the desired effect for 10 percent of the work, use the simpler solution.

  • Isolate complexity as much as possible.

  • Provide mechanism, rather than policy.

Bundling VMODs with the Varnish distribution

Decisions about whether to add a new Varnish module (VMOD) to those bundled with Varnish are guided by these criteria.

  • The VMOD is known to be in widespread use and in high demand for common use cases.

  • Or, if the VMOD is relatively new, it provides compelling features that the developer group agrees will be a valuable enhancement for the project.

  • The VMOD does not create dependencies on additional external libraries. VMODs that are “glue” for a library come from third parties.

    • We don’t want to add new burdens of dependency and compatibility to the project.

    • We don’t want to force Varnish deployments to install more than admins explicitly choose to install.

  • The VMOD code follows project conventions (passes make distcheck, follows source code style, and so forth).

    • A pull request can demonstrate that this is the case (after any necessary fixups).

  • The developer group commits to maintaining the code for the long run (so there will have to be a consensus that we’re comfortable with it).