Finally A Code Layout That Works!

Background

Our team develops software that evolves around robotics/vision. Speaking in software terms we do not have a single product but rather a set of continuosly growing libraries which are integrated in a set of applications. From the very first moment on we headed for modularized software components, to factor out common code.

Our team consists of ~ten members of which five contribute to the code on a daily basis. We use a versioning control system and build server for continous integration and track our bugs.

For a developer working on a specific project the code layout on his/her computer harddisk resides in a single project directory containing a flat hierarchy where each library/application resides in a single directory

sample_project
  +---app_a
  +---lib_a
  +---lib_b

Within the version control system, however, the code is organized differently. Each library/application is a project on its own. It links to required libraries by including them as externals. Quite often projects consist of tens of externals which makes the projects extremely hard to maintain.

What's the new layout?

In the version control system there is just a single robotics/vision project containing libraries and applications as single sub-directories.

The trunk contains stable libraries of general interest only. Applications and customer specific code will reside in branches of the trunk. Additionally we set up the following three simple rules.

• No one, except the maintainer, commits to the trunk.
• The trunk contains libraries that are of general interest.
• Any code in the trunk exhibits tests and documentation.

Ideally the maintainer is a person that not actively contributes code. That way, all requests to integrate code in the trunk have include unit tests and at least a description of the feature/bugfix to be integrated. Otherwise, how should the maintainer verify rule #2 and #3?

From the rules it is obvious that the trunk will show only single commits for a single feature/bugfix. That eases the merging of features back into branches and allows for a readable changelog.

As anyone is actually working on branches of the trunk, project leaders are free to decide if and when to integrate features/bugfixes from the trunk.

Our build server will continously build the trunk and run all of its tests. Registering a branch for continous integration is only a matter of cloning the build project of the trunk.

Code => Trunk

One of the questions worth asking is: How to motivate people to contribute code to the trunk? There probably is no simple answer to this question. It depends, beside other reasons on

• communication: high level of communication between team members will keep everyone updated on what others currently work on. So sentences like "oh nice, could we have this in trunk? I need it too" should occur often.
• the background/education of team members: influences their inner drive to modularize code and actively contribute to the trunk.

Please feel free to criticize.