Approach to Source Control for Small and Mid-Sized Organizations

Target Audience

This guide provides team-development guidelines for lead developers, developers, test team members, and system administrators. Read this guide if you plan to, or currently work on, a team-based development project with source control measures

What you should know

To use this guide to establish a team development environment and a development process suited to Source Control, you must have some development experience with a Source Control tool. You should also be aware of the general issues and challenges traditionally associated with team-based software development projects. Ideally, you will have some experience with a Source Control system, like Microsoft�s Visual SourceSafe. You should be very conversant with the purpose and use of features such as Pinning, Labeling, Branching, etc.

Note: This guide focuses on the use of VSS version 6.0c (the version that ships with the enterprise editions of Visual Studio .NET) as the Source Control system. However, much of the guidance and many of the discussed processes apply equally well to other change management systems, many of which can be directly integrated into the Visual Studio .NET IDE.

Introduction

Firstly, I�d like to point out how limited the number of articles there are in existence for a topic as vast as Source Control. Also although the concepts and approaches have been more or less tirelessly discussed and agreed upon, there always seems to be a lack of more approachable and user-friendly documentation. With this article, I would like to conquer if not all at least just the tip of the ice-burg.

Extract from Microsoft:

"Source Control is as much a way of thinking about software development as it is a tool. It can facilitate parallel development and enable developmental isolation, but it can ensure neither. Only by establishing and following through on a strategy can a team use Source Control to its fullest potential"

My experience with Source Control started 4-5 years ago when development with a team turned out to be more of a nightmare than just a project. Way back then we had evaluated a couple of tools on Source Control and finalized on Microsoft�s Visual SourceSafe due to the conveniences it offered on integration with Microsoft�s development tools.

Although the decision was quite prompt, integration was another matter all together. For stand-alone GUI applications integration was as advertised by Microsoft - A piece of cake. But for web based applications, it was far from it.

This article�s focus being more on the approach towards Source Control; integration issues and their resolutions are not covered here, you may however read about integration steps and issues with Microsoft Visual SourceSafe (VSS) and Microsoft Visual Interdev in one of my later articles. But the reason I mentioned the said integration issues is that were it not for a well planned out approach strategy; the issues would have been humungous.

Access control and roles assignments

So coming to the point, the approach towards Source Control for mid sized applications. First, I believe that as a rule to Source Control through any tool; setting the authorization roles and providing permissions is the starting point.

Following is a chart of the basic roles and the privileges that should be provided:

Main roles

Administrator

As the administrator, it is your job to make the files in the Source Control database as useful to the clients as possible. Features such as granting permissions, creating users, etc. are your duties. You also by default have the full permissions on all folders and projects.

Configuration controller

As a configuration controller, you are responsible for the implementation of configuration management activities within the project.

In order to achieve the above, your interaction with the Source Control approach is the highest. You must ensure that the changes to the identified software work products are controlled and that the integrity of the configurable code is maintained.

Release controller

As a release controller, you are the custodian of the source code released by configuration controller. It is your duty to manage the release of the final product making it live as per the project�s plan.

Directory and folder structures

Now we come to the Directory/Folder structure (specified above) - also known as project structure in Visual SourceSafe terminology. Below is an exhibit of the kind of folder structure that should ideally be followed:

At a more detailed level below is an extract of what structure should be like with some sample projects:

Directories
- $/
   - 1 Development

       - 1 GUI Projects
        - 1 Visual Basic Projects
                + 1 XYZ Project
                + 2 ABC Project
                + 3 LMN Project
        + 2 PowerBuilder Projects

       - 2 Web Projects
            + 1 XYZ Project
            + 2 ABC Project
            + 3 LMN Project

    - 2 Quality Assurance
       - 1 GUI Projects
        - 1 Visual Basic Projects
            + 1 XYZ Project
            + 2 ABC Project
            + 3 LMN Project
        + 2 PowerBuilder Projects

       - 2 Web Projects
        + 1 XYZ Project
        + 2 ABC Project
        + 3 LMN Project

    + 3 Production
    + 4 Branches
    + 5 Documents & Archives

Directory and folder structures (Cont.)

Let�s go into more details on the reason for recommending the said structure. At the first glance you will see that the folders are logically grouped into six main areas - namely:

1. Development

This folder will contain project files with complete access permissions to all developers concerned. The root purpose of this folder is to provide developers with the controlled environment in which they need to check out and check in their code and make modifications as and when required.

You will note in the above illustration that this folder is further sub-divided into source and webs folders. They are the ones that actually contain the project files for developers to work on. This logical break up provides not only ease of understanding and use to developers but also the flexibility to grant/revoke permissions on Source Control.

2. Quality assurance

This folder is nothing but a mirror of the Development folder. An actual mirror, but with access restrictions. This folder will contain a share of all the project files in the Development folder. These files will also be pinned to the latest version of the projects available for Testing/Quality assurance.

The purpose of this folder is to allow only configuration controllers access to project files that are to be distributed to quality assurance teams for their usage/testing. Again as mentioned above they will not be physical project files but a shared and pinned version of the Development folder. Once the files are shared and pinned correctly in this folder the configuration controller may distribute the latest version or provide read-only access to the structure for the relevant teams. In addition, developers may continue their development independent of the testing team. Version and history information will still be appended to the said files as and when check-in/check-out happens. However due to the pinning process only that version of the file will be available for Quality Assurance.

3. Production

Again this folder too is like a kaleidoscope, containing the same physical files shared from Development folder and pinned to the actual version on production servers. A distinguishing place where a single file can provide information of which version is on the development servers modifiable to developer and which version is available to customers of the project files using the said code on production.

4. Branches

This is a key folder to note playing its intricate part in the patterned design for Source Control. This folder�s purpose may be better explained with an example:

Suppose a project that has been distributed across the above three folders is now live and in production however it now requires a bug fix. Also let�s suppose that the particular module requiring the bug fix is already being worked on in the development area as part of a new launch.

To put it in simpler language: Module A is pinned at version 2.0 on Production. On Development it is being worked on towards version 3.0. There is a bug in version 2.0 and needs to be fixed there by incrementing the file to version 2.1.

In such a scenario, the file needs to be modified and tested without rolling back the current changes done towards version 3.0. Here in comes the use of the Branches folder. Thanks to this folder�s existence, the Configuration Controller may share and branch the said file from the Production folder into the Branches folder (the version pinned on Production will be provided).

This file may now be given to developers to incorporate the bug fixes on (version 2.1). Once the changes are done, the file may again be moved into Quality Assurance and Production as the need may be. Later on the bug fixed version 2.1 may be merged with the file in Development Version 3.0 so that the needed bug fix and enhancements are in place.

5. Documents and archives

Are self-explanatory folders. Documentation and project archives may be kept in these respective folders.

And finally

Once you have the authorization and the above recommended folder structure in place all that�s left are the policies and procedures so critical and unique to each organization. A suggested process for New and Maintenance projects is provided below.

For Maintenance Projects

• User requests a change and informs configuration controller assigned for the project.
• Assigned developer will have access to Development folder (as shown in matrix above) to checkout required files.
• Assigned developer�s responsibility to add check-in comments on completion.
• Assigned developer to update and inform the configuration controller to pin / un-pin the required files in the Quality Assurance folder.
• Assigned developer will also co-ordinate with UAT team for the commencement of UAT.
• Upon receiving confirmation from UAT team, assigned developer informs Configuration Controller to pin / un-pin the required files in Production.

For new projects:

• A Project folder must be created in each of the required project folders (Development, Quality Assurance and Production) by configuration controller along with providing access rights.
• For testing purposes, configuration controller will share / pin the files in the Quality Assurance folder.
• On launch, configuration controller will share / pin the files in Production folder.
• Further changes after launch will be through the process given in the Maintenance projects section above.