Difference between revisions of "OpenVPN/Developer documentation"

From Secure Computing Wiki
Jump to: navigation, search
m (Development process)
Line 8: Line 8:
  
 
* All patches must be sent to "openvpn-devel" mailing list for review
 
* All patches must be sent to "openvpn-devel" mailing list for review
* All patches need to be reviewed and accepted (ACK) by at least two developers to make sure they meet our quality requirements
+
* All patches need to be reviewed and accepted (ACK) by at least two developers to make sure they meet our quality criteria
 
* All accepted patches go to the OpenVPN "testing" tree (Git) first
 
* All accepted patches go to the OpenVPN "testing" tree (Git) first
 
* Code is moved to the OpenVPN "stable" tree (SVN) after initial testing
 
* Code is moved to the OpenVPN "stable" tree (SVN) after initial testing

Revision as of 04:32, 17 February 2010

Introduction

Most of the content here is the result of the the weekly IRC discussions.

Development process

The basic development process we follow is outlined in this diagram. So, in a nutshell:

  • All patches must be sent to "openvpn-devel" mailing list for review
  • All patches need to be reviewed and accepted (ACK) by at least two developers to make sure they meet our quality criteria
  • All accepted patches go to the OpenVPN "testing" tree (Git) first
  • Code is moved to the OpenVPN "stable" tree (SVN) after initial testing
  • All official releases are based on the "stable" (SVN) tree and go through a feature freeze and a Beta/RC process

If someone maintains their modifications in a git tree already, those git trees can be pulled as long as it will not cause any conflicts against the master/SVN development branch. However, the author must send a pull request to the devel mailing list so that the changes can be discussed publicly.

NOTE: Patches sent directly to a development tree ("stable" or "testing") maintainer will be rejected. All patches must be public and must be discussed in public.

Code quality, standards and conventions

WIP, see this and this for now.

All patches need to meet certain quality criteria before being accepted:

  • All patches should be useful and beneficial for several OpenVPN users. This way we avoid spoiling the code base with features which is only requested for very special conditions.
  • All patches must contain an argumentation for *why* this patch should be included and *how* it solves the issue in plain English.
  • Everyone who has contributed to this patch should be mentioned, with at least a valid e-mail address, preferably with full name in addition. This is to give credit to contributors.
  • All patches must be against the SVN development branch or git master branch, at least until a feature branch is created.
  • Patch should apply cleanly without a bunch of merge conflicts
  • All initial patches must be sent as unified diff (diff -u)

Code repositories

Old CVS repository

There is an old CVS repository hosted in SF.net. This is not used for any development.

Stable (SVN) repository

The OpenVPN project makes use of two code repositories. The Stable SVN repository is maintained by James Yonan and hosted at openvpn.net. Instructions for using it can be found here. Currently (Feb 2010) only James has write access to this repository, but anonymous read-only access is available.

Code from this repository should be used if stability is important for you, but the official releases are missing some essential piece of functionality.

Testing (Git) repository

The Testing repository is maintained by David Sommerseth and uses Git. This repository is hosted by SF.net under the OpenVPN project.

There are several branches in the Git tree, each of which tracks the different patches/contributions separately. There's also one branch that contains all the available patches:

    master	  -- Should be identical to James' stable SVN development branch
    bugfix2.1    -- Contains only bugfixes for OpenVPN 2.1
    {featureX}   -- Contains only patches for feature X
    {featureY}   -- Contains only patches for feature Y
    {featureZ}   -- Contains only patches for feature Z
    allmerged    -- All branches above merged

This gives James ("stable" branch maintainer) a possibility to only include/merge in the features and bugfixes which he wants to include into his development branch. And if he wants it easy, and see that all branches have been tested enough he can just merge in the 'allmerged' branch.

It is expected that each contributor which have received a feature branch makes sure it merges cleanly against the development branch at any time. The same applies to maintainers of external development Git trees. Also, the development of the feature branch is the author's responsibility - "testing" tree maintainer only collects the patches and makes sure all features and bugfixes play nicely together to catch conflicts as early as possible (and of course do sanity review of all patches).

Generic instructions for using Git in SF.net can be found here. Generic usage instructions for OpenVPN project's Git repository can be found here. To fetch the latest development code, use

git clone git://openvpn.git.sourceforge.net/gitroot/openvpn/openvpn-testing.git

Use this code if you want the latest and greatest features and you're willing to encounter problems. If you're unfamiliar with Git in general, take a look at these links: