Development Practices


This page needs to be reorganized

This page describes some conventions we use when documenting, building, testing and packaging Contrail software components.

Source Code

Organization

The structure of the source code repository is described in the Source Repository page.

Here are some general rules developers should follow when structuring their projects:

  • Don't write or delete anything in the root directory (trunk/)
  • Put the project's directory in one of common, federation, resource, network, conpaas directory
  • Don't commit configuration files or data files (see svn ignore)
  • Add a README file
  • Prohibit non ASCII characters in all files and directories name
  • Try using only lower case letters in directory names

Commit Hooks

The Subversion commit hooks are used to enforce some quality criteria when a developer commit its source code.

If one rule is violated, then the commit is rejected with one of the following error messages:

Error MessageCauseSolution
server or connection errorThe hook script failed to examine the transactionTry with smaller data
source code is currently frozenCommit has been temporarily forbidden by administratorsRetry later
commit message is blank or emptyInvalid commit messageDescribe your modifications
trying to modify the repository structureAttempt to modify one of the top level directoriesNone, the repository structure can only be modified by administrators
trying to commit configuration filesAttempt to add or update one of .classpath, .project, .DS_Store, .settingsRemove them or configure svn to ignore them (see global-ignores option)
trying to commit data filesAttempt to add or update a file matching *.logsame as above

Naming Packages

For every Contrail component, the maven groupId should be org.ow2.contrail.{common|conpaas|resource|federation|network}.
If the groupId is wrong, bamboo will fail when trying to upload it onto the repository.

Maven Parent

Some Contrail components are not (yet) build with Maven, but we still use maven to run their build procedure and upload the resulting artifact in the repository.

Every pom.xml file should contain a reference to the project's parent pom. For example:

<dependency>
 <groupId>org.ow2.contrail</groupId>
 <artifactId>contrail</artifactId>
 <version>0.1</version>
 <type>pom</type>
</dependency>

Best Coding Practices

We encourage Contrail developers to read more about Best Coding Practices.

Some old but good books:

  • Steve Maguire, ``Writing Solid Code'', Microsoft Press.
  • Steve Maguire, ``Debugging The Development process'', Microsoft Press.
  • Steve McConnell, ``Code Complete'', Microsoft Press.

Documentation

All the Contrail documentation should be available in the Documentation Space of this wiki.

However some of the documentation can also be generated from sources (e.g. javadoc, LaTeX...)

Build

The list of all automation tools we use is in the Development Tools page.

Target Names

This table shows the common target names we use with automation tools:

Automation ToolBuildTestPackageInstallGenerate Documentation
makebuildcheckdistinstalldoc
antcompiletestpackageinstalljavadoc
maveninstalltestpackagesite

For every automation tool we use in Contrail, Build should be the default target (i.e. the one called when no target was specified).

Build Phases

Lifecycle

Automation ToolGuideline
MakeMake targets are the usual GNU-style targets (think of the ones generated by automake).Using GNU autotools in your project will create a compliant build system and is thus strongly recommended.
Ant
MavenFor Maven compilation, testing and installation, we conform to the usual phases of the Maven lifecycle.

Compilation

Tests

The test suite should fail if at least one unit test fails.
For more details on testing, please read the Testing page.

Packaging

The install target should install executables (libraries, documentation, configuration and data files) to FHS-compliant paths

Installation

Make

installs files relative to DESTDIR variable.

make DESTDIR=/some/path install

should install executables to /some/path/usr/bin, libraries to /some/path/usr/lib etc.

Maven

Installation will be performed with the assembly plugin with the single goal bound to the package phase.

This requires writing an assembly descriptor.

An example of maven assembly descriptor can be found  here. Assembly plug-in should be added to the  pom.xml:

<build>
<plugins>
 <plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <version>2.2.1</version>
  <configuration>
   <descriptors>
    <descriptor>src/main/assembly/package.xml</descriptor>
   </descriptors>
  </configuration>
  <executions>
   <execution>
    <id>make-assembly</id>
     <phase>package</phase>
     <goals>
      <goal>single</goal>
     </goals>
   </execution>
  </executions>
 </plugin>                        
</plugins>
</build>

Installation

Directories

In general, we will use a standard Linux directory tree:

Filesystem PathExpected Content
/usr/share/javathe built jars,
/usr/share/contrail/vinscripts, static binaries, etc., used for vin,
/etc/contrail/vinconfiguration files,
/var/lib/contrail/vinworking space for any persistance files, databases, lock files, etc. that are created during the runtime and need to stick around in the system between runs,
/usr/share/binhere we put symbolic links to the scripts and binaries installed elsewhere, for the CLI.

FHS-compliant paths under a given base directory.

  • In Java, dependencies should come from outside, pre-installed on the target system, and then referenced in the start-up script. 
  • For the users' convenience, the components should include scripts that will call java, ruby or other components from command line.

Configuration Files

It is crucial that all changeable elements of the component can be manageable in a text file with the configuration.
By convention, the configuration files should have a simple KEY=VALUE structure. The KEY can be a namespaced (e.g. vin.agent.name).

The development environment should contain all the configuration files with pre-filled default values.