[[TOC(inline, depth=1)]]

= Introduction =

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

= Developer communication channels =

There are two primary developer channels:

 * '''[http://sourceforge.net/mail/?group_id=48978 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:

[[Image(wiki:DeveloperDocumentation:getting_code_to_openvpn.png,100%)]]

In text format:

 * Patch is sent to "openvpn-devel" mailing list for public review
 * Patch [wiki:PatchReview 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 ([wiki:CodeStyle 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:

 * [http://mywiki.wooledge.org/Bashism Bashism - Greg's Wiki]
 * [http://sourceforge.net/projects/checkbaskisms/ Checkbashisms]: a tool to check for "Bashisms". Also included in Debian/Ubuntu "devscripts" package.
 * [http://gondor.apana.org.au/~herbert/dash 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 [http://chris.beams.io/posts/git-commit/#seven-rules 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 [https://git-scm.com/docs/git-send-email 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:

 * [wiki:GitCrashCourse git crash course]
 * [http://git-scm.com/ Git homepage]
 * http://progit.org/book/
 * http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
 * [http://git.or.cz/course/svn.html git for SVN users]

= Code repositories =

See CodeRepositories page.

= Practical issues =

See DeveloperTips page.