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. Term Definition 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 1.6.2.2. 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 &app; 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. Since the &app; 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 &app; 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. Access to the repository is available in two different forms Read-Only access Read-Write access Read-Only access is granted to anybody anonymously to the repository. For this type of access you do not need a user account on the SourceForge platform. Access is made through the pserver-protocol of &cvs;: See the description on SourceForge for more details. In order to get read-write access to the repository, two things are necessary. First you need a user account on the SourceForge platform. Second you need to qualifiy as a developer with the &app; project administrator(s). Once they have added you to the list of developers, you can access the repository through an SSH encrypted tunnel. See the description on SourceForge for more details. This chapter explains which files have to be version controlled. It also explains how to configure &cvs; to skip certain files that are generated by the compile/build process but should not be stored in the repository. All files that form an application (e.g. source code, header files, icons, documentation, etc.) that are necessary to compile, build and run the application must be checked into the central repository. Before you add a file to the repository you must check it's format. If it's a binary format the special option -kb must be appended to the cvs add in order to inform the central repository to leave the file as it is All files that are automatically generated by the build process (e.g. object files, libraries, executables, Makefiles, etc.) should not be checked into the repository because they can easily be reconstructed by the developer. In very rare circumstances it might be necessary to checkin an automatically generated file. This is always an exception. I mentioned Makefiles above because I assume that ∾ and &am; are used. Using ∾ and &am; supplies the project with a configure script that creates the Makefiles. The necessary input files are called Makefile.am that must be checked into the repository as source to the Makefiles. If you do not use ∾ and &am; and write your Makefiles directly, they have to be checked in as they are not automatically generated. Nevertheless, using non &am; generated Makefiles should be avoided. At certain times to be defined by the project's administrators (actually configuration manager) a snapshot is taken from the repository. In order to fix the stage of this snapshot in the repository, a tag is placed on this stage. Tagging the repository creates a version of the project. The version number is made out of three numeric fields. These are: The major release number The minor release number The micro release number In order to serve as a tag for &cvs;, the text rel- is prepended to the version numbers and the three fields are seperated with a dash (e.g. rel-0-3-7). The major release number will be changed when all the proposed features mentioned in the release plan (available on the project web-site) are designedi, coded and tested. One of the objectives of the minor release number is to differentiate between stable and unstable versions of the project. As a widely accepted procedure, odd numbers are used for development versions, even numbers identify stable versions. Whenever the configuration manager decides that to create a new stable release, this will also bump the version number of the unstable release by two. The micro release number is reset to 0 when the minor release number is incremented and then incremented with each version following until the minor release number is modified again. Versions tagged between the creation of a stable branch and the actual release -0 of this branch will be identified by a micro release number of pren, where n is incremented each time a version is tagged.