Version control

A version control system is useful when working on a collection of files that evolves over time, in particular if several people are modifying the files. For example, version control is often used in software projects to store the code in a way that several developers can access and contribute to the code without the need to send files by e-mail etc. Another example is when you are writing a paper with your colleagues and you need to efficiently and safely share your additions to the paper. A version control system also keeps track of the history of your contributions; most version control systems can be used to retrieve the state of your files as of a given date. This means that there is no need to create local back-up copies. To make it short and sweet: version control means you can relax.

The version control system Subversion is installed on one of our servers. Currently, it is used for a number of research projects, some master's thesis projects and for the projects in the Project in Automatic Control course. If you would like to try out version control, talk to Johan Åkesson in order to have a repository for your files set up.

Guidelines for using Subversion

An excellent source of knowledge about using Subversion can be found at http://svnbook.red-bean.com/. Here you will find basically everything you need (and more) to use Subversion efficiently. Some basic guidelines for using Subversion are:

• A typical Subversion repository has three directories at the top level: 'trunk', 'tags', and 'branches'. Development usually takes place in 'trunk', so all the project files should reside there. 'brances' are typically used to create snapshots of the trunk to enable concurrent development, and 'tags' are used to mark releases. See the Subversion book for more info.
• Try to make atomic commits, meaning that each commit has a well defined scope. I several unrelated changes has been made to the code commit them separately. A good practice when using Subversion in association with trac is to always work with a particular ticket i mind. In this case, a commits are normally done in relation to tickets.
• Be careful to use the log-message facility. This makes it much easier to trace the origin of code changes. If Subversion is used with trac, a reference to a ticket should normally be included in the log-message. Also, when a commit is made in relation to a ticket, it is useful to also add a reference to that commit in the trac ticket.

Project planning with Trac

In some larger, software-oriented projects involving several developers, it is useful to have a tool for planning, coordination, and documentation of the work. For this purpose, we now have the option to use Trac. Trac is a web and wiki-based planning tool in which tickets/bugs can be registered and assigned to developers, milestones defined. Trac is also integrated with Subversion.

The user's guide for Trac is integrated with the system itself. The following guidelines summarizes basic usage of Trac.

• - Read the Trac documentation, and in particular the material related to wiki formatting and trac references.

The name space for wiki-pages is global. Therefore, it is important to use a convention that does not introduce conflicts. Here we use the CamelCase (http://en.wikipedia.org/wiki/CamelCase) strategy for naming wiki pages in combination with name mangling where CamelCase names are concatenated and separated with slashes ('/') to create a hierarchical structure. For example, if the wiki page 'GuideLines' is created at the top level, a typical name of a sub-page is then 'GuideLines/Trac'. Notice that 'GuideLines/Trac' is considered by trac as a global name and not a hierarchical one.

• - Tickets typically follow a life cycle:
  • - The ticket is created and a description is added. - The ticket is accepted by a developer that undertakes to perform the task specified in the ticket. - The ticket is resolved, usually by 'fixed'.
    • There are also other options:
    - If a duplicate ticket is created, it can simply be resolved as 'duplicate'. This resolution is used also when a ticket is divided into two or more new tickets. Sometimes it is useful to create a very general ticket which is then divided into more specific ones. In such case, make sure that the new tickets refer back to the original ticket. - For some tickets it may be decided that the task will not be performed, for some reason. In this case, the ticket is resolved as 'wontfix'.
  - Make frequent use of cross-references between tickets, wiki pages and subversion revision numbers. In particular, it is important to add a reference from a ticket to a subversion commit whenever a commit is made relating to the particular ticket. Conversely, try to always add a reference to a ticket in subversion commit comments. This makes it much easier to search and trace the origin of code changes. Tickets are referred to using the syntax '#1', revisions by 'r1'. Please also see the trac documentation for more information on wiki formatting and trac references. - The 'component' field of a ticket is used to classify tickets and group them into different categories. Different projects typically have the need for different components and are accordingly created based on the specifics of the particular project. Since adding components requires admin privileges, please contact the trac administrator if new components need to be added.