wiki:DeveloperDocumentationNew

Introduction

This page outlines the development practices for the main OpenVPN project. The information here is mostly applicable to our other subprojects (e.g. openvpn-gui and openvpn-build), except that they allow GitHub pull requests unlike in the main project.

Developer communication channels

There are two primary developer channels:

  • openvpn-devel mailinglist: primary communication channel, subscription required
  • #openvpn-devel (at) irc.freenode.net: used for generic development discussions and the weekly IRC meetings

Development process

The basic development process is outlined in this diagram:

In text format:

  • Patch is sent to "openvpn-devel" mailing list for public review
  • Patch will be reviewed and either accepted (ACK) or rejected (NACK). The ACK consists of two parts:
    • Feature-ACK: does the patch make sense to have?
    • Code-ACK: does the patch meet our code quality standards?
  • Accepted patches go to the Git "master" branch

GitHub pull requests can be used to preliminary review especially for large patchsets. The final patches, however, must go to the openvpn-devel list.

Making patches

Basic requirements

  • Patches should generally be written against the Git "master" branch.
  • Patches must apply cleanly, without merge conflicts.
  • Patch must pass all applicable automated testing (Buildbot and/or Travis)
  • Large features may need #ifdefs so that they can be disabled on embedded systems. The developers will let you know if this is the case.
  • Man-page and Changes.rst should be updated as necessary.

Code style

OpenVPN 2.3 and earlier use mostly the following conventions:

  • Indentation is 2 spaces (no tabs)
  • Indentation follows GNU Coding Style
  • Emacs
    • c-style gnu
    • c-basic-offset 2
    • indent-with-tabs nil

OpenVPN 2.4 uses the Allman style (full documentation):

  • Indentation is 4 spaces, no tabs ever.
  • Opening and closing brackets get their own line, and must match indentation.
  • Line length is 80 characters.
  • C99 is allowed. E.g. for (int i = 0; i < max; i++).
  • Only use /* */-style comments

Notes on Shell scripts

Patches to shell scripts such as those in easy-rsa should be POSIX-compliant for portability reasons. If the existing scripts don't fulfill this requirement, don't hesitate to provide a patch fixing that.. He're are a few links to relevant resources:

Commit message

Patches must have a short but descriptive one-line summary of the change, followed by a more descriptive text explaining in plain English why and how the patch is written. This description should not be too technical, as the patch itself will reveal the technical details. The patch should also conform to these rules (adapted from here):

  • Separate subject from body with a blank line
  • Limit the subject line to 50 characters
    • NOTE: this limit is under discussion
  • Capitalize the subject line
  • Do not end the subject line with a period
  • Use the imperative mood in the subject line
  • Wrap the body at 72 characters
    • NOTE: this limit is under discussion
  • Use the body to explain "what" and "why"

In addition:

  • Add a 'Signed-off-by:' line at the end (git commit --signoff).
  • Everyone who has contributed to this patch should be mentioned out of courtesy. Use a valid e-mail address and the full name whenever possible.

Sending patches

We strongly encourage configuring and using git send-email for sending the patches, so that your email client does not mess the formatting. For example, to send your latest commit as email:

$ git send-email --to=openvpn-devel@lists.sourceforge.net HEAD~1...HEAD

Using Git

If you're unfamiliar with git in general, take a look at these links:

Code repositories

See CodeRepositories page.

Practical issues

See DeveloperTips page.

Last modified 17 months ago Last modified on 02/07/17 13:46:00