Table of Contents
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:
- Bashism - Greg's Wiki
- Checkbashisms: a tool to check for "Bashisms". Also included in Debian/Ubuntu? "devscripts" package.
- DASH: a minimal shell with "POSIX-compliant features only", probably useful for testing
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:
- git crash course
- Git homepage
- http://progit.org/book/
- http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
- git for SVN users
Code repositories
See CodeRepositories page.
Practical issues
See DeveloperTips page.