Development Practices
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 Message | Cause | Solution |
---|---|---|
server or connection error | The hook script failed to examine the transaction | Try with smaller data |
source code is currently frozen | Commit has been temporarily forbidden by administrators | Retry later |
commit message is blank or empty | Invalid commit message | Describe your modifications |
trying to modify the repository structure | Attempt to modify one of the top level directories | None, the repository structure can only be modified by administrators |
trying to commit configuration files | Attempt to add or update one of .classpath, .project, .DS_Store, .settings | Remove them or configure svn to ignore them (see global-ignores option) |
trying to commit data files | Attempt to add or update a file matching *.log | same as above |
Naming Packages
For every Contrail component, the maven groupId should be org.ow2.contrail.{common|conpaas|resource|federation|network}.
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:
<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 Tool | Build | Test | Package | Install | Generate Documentation |
---|---|---|---|---|---|
make | build | check | dist | install | doc |
ant | compile | test | package | install | javadoc |
maven | install | test | package | site |
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 Tool | Guideline |
---|---|
Make | Make 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 | |
Maven | For 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:
<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 Path | Expected Content |
---|---|
/usr/share/java | the built jars, |
/usr/share/contrail/vin | scripts, static binaries, etc., used for vin, |
/etc/contrail/vin | configuration files, |
/var/lib/contrail/vin | working 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/bin | here 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.