Chapter 1. Configuration Management

Table of Contents

Version Control Tool
Access to the repository
Read-Only access
Read-Write access
Version controlled files
Files that must be stored in the repository
Files that should not be stored in the repository
Version management
Layout of the version numbers

Whenever a project is developed in stages, it is very important for the people working on the project to know, which version of the project is used by the users and how it was built and what the components of this project are. This applies to hardware (e.g. automobiles) as well as software. Think of the times, when a car manufacturer calls certain cars to be repaired due to production problems. The manufacturer can track down the relevant cars because he is using a configuration management system and knows each car that contains e.g. faulty parts.

The same applies to software development projects: whenever a version (stage of development) of the project is made public, it has to be given a distinct name or tag - usually the version number - and the development team must keep a snapshot of all components that made up that stage of the software project. This does not only include the source code of the project, but all libraries in their relevant stage as well as compilers and tools and all their installation/configuration information. If all this information is present, the software development team is capable to exactly reproduce each delivered version to search for problems occuring with this version. If this capability is not available, the development team has a hard time to find these problems.

CVS helps us in our project to cover one aspect of configuration management: version control of the source code. It helps us to keep the snapshots of all the files the project team is responsible for in a central repository. Another aspect of CVS is concurrent development which allows us that some of us can develop new features of the project while others fix problems with previous versions even if both tasks modify the same source file. This feature is called branching. How branches will be organized in our project is explained in the chapter about Version management.

The configuration management also regulates how the development team passes information among the members. This includes things like naming conventions, how errors are reported, rated and fixed and who is responsible for which task. The emphasis on this document though is the management of the version control system and how things are handled in this area. This does not mean, that the other important issues of configuration management are left outside. They are just not in the focus of this document.

Throughout this document a few terms are used. In order to avoid confusion because these terms might be used differently in other documents, they are defined here.

Table 1.1. Definition of version control related terms

Revision A revision is the stage of a single file in the repository. Revisions start with the value 1.1 upon the initial check-in and are incremented with each check-in of that file. After the third check-in, the revision of a file has the numeric value of 1.3. Once branches are made, revisions can have values like Since the revisions differ for all files, the revision number is only necessary for certain administrative tasks on single files (e.g. merging data from another branch).
Tag, Label A tag is a string that represents a single revision of a file. Multiple tags can point to the same revision of a file. Sometimes, label is used as a synonym for tag.
Version A version is the stage of the whole project in the repository. As already mentioned, the revisions for the files contained in the project differ from each other for a specific version. Therefor, each revision contained in a version receives the same tag. This tag can be used to checkout an exact copy of the version of the project.
Repository The repository is the central database containing all revisions of all files of the KMyMoney project. It is located on the SourceForge.net and can be accessed via CVS.
Sandbox The sandbox is the local work area for the developer. Initially, a sandbox is filled by checking out a specific stage of the repository. Changes made to the sandbox are moved to the repository by the checkin process. Changes made by other developers are transferred to one's own sandbox by the update process. A developer can maintain different sandboxes of the same project in different directories on the same machine. This requires thorough attention of the developer which sandbox he is modifying. Using several sandboxes is usually meaningful if a developer works on changes on a release branch (stable release) and on the main-branch (development release) at the same time. See the appendix for an example.

Version Control Tool

Since the KMyMoney project is hosted on the SourceForge platform, CVS is used as the version control tool. CVS is widely accepted as version control tool in the open source community and covers our needs pretty well.

The KMyMoney project's central repository is handled on the SourceForge platform. Developers do not edit files directly in the repository, but rather checkout a working copy into their local sandbox. This local sandbox can then be modified without the necessity of a direct link to the central repository. Once the developer is confident with the changes made, he checks the files back into repository.

During the checkin process, CVS keeps track of all the changes made. This allows to review a complete history of all modifications ever made to the project. As mentioned above, it is very important in certain circumstances to have such a history.