Seapine Labs
Personal tools

Best Practices

From Seapine Labs

Jump to: navigation, search

This document addresses some of the common activities in Surround SCM and offers best practices for each. These best practices are designed with Surround SCM users in mind, but many of them are general software configuration management (SCM) suggestions that apply regardless of the tool.

With that said, the overriding best practice in software development is to use an SCM tool. Copying directories on a shared network resource and renaming them to create a new release is not the same as branching. Backing up code regularly is not the same as version history. Understanding software configuration management and using a tool like Surround SCM streamlines your development process and greatly reduces the stress of managing the development process. These best practices are guidelines, and your business policies should dictate if you follow a practice.


[edit] Repository structure

A repository stores your source code and its history within the Surround SCM database. While you can think of a repository as a directory structure, a repository has a key difference-history. A repository tracks files over time and saves all previous versions so you can access them in the future. It also records who made the changes, when, and why. Since the number of files will grow over time, it makes sense to do some planning before you start adding files.

[edit] Repositories versus branches

Before deciding upon a repository structure, it is important to understand the difference between repositories and branches. A repository is a central place where data is stored. It is a collection of files and other repositories. It is generally mapped to a hard drive directory and is used to organize files. View a screenshot of a repository that contains source code organized by products.

A branch is a separate line of development that uses an existing repository and its files as a starting point. Branching allows users to work on multiple versions of a product simultaneously while using the same set of source files. A branch represents a milestone in development. Its primary purpose is not to store files but to provide a separate area for development or to represent the code at a point in time. View a screenshot that shows a branching structure for different releases; the WysiCalc 1.0.0 Final Release branch was created from the WysiCalc repository on the mainline.

Do not create branches just to organize files. For example, if you are developing a new product, do not automatically add a branch for the new product. Instead, create the required repository structure in the mainline-the top-level branch that contains all repositories and branches. Then develop at that level until are ready to create a release or need to begin parallel development.

[edit] When to add files to a repository

When you create a new product, it is not necessary to add every file to the repository as soon as you create it. You can work on local copies of the source code for some time before you add them to the repository. A good rule of thumb is to add files to Surround SCM after they build successfully. If your workstation is not backed up regularly or if you are working remotely, you can add your files to Surround SCM without performing a build to protect your changes. If another developer needs to work on one or more of the files, add them to Surround SCM so you can track the changes made by different developers.

[edit] How to structure a repository

Perhaps the easiest repository structure to maintain is one that has a repository for each product or application on the mainline branch. Then add the files and appropriate directory/repository structure under each repository.

[edit] What to include in a repository

Because Surround SCM stores files and the change history for those files, the Surround SCM database can grow exponentially. In general, you only need to store the source files necessary to create a product. Do not store binary files that get generated during a build (such as executables and object files) in Surround SCM. You can regenerate those files if you have the source code and build scripts. This practice can save significant space. You can include the binary files if you need to version these files or if the time required to regenerate them outweighs the space considerations.

It is also important to include project-related documentation with your source code. This includes requirements, functional specifications, technical designs, and policies. The design of an application can change, and storing design documents in Surround SCM allows you to specify the definitive design that all team members should refer to. In this screenshot, the Documents repository contains both the user documentation and the project documents.

[edit] Branching

Branching is a balancing act. The right amount of branching can provide clarity to your development cycle and improve productivity by allowing for parallel development. Too many poorly defined branches can cause confusion and result in unnecessary merging of code. Not enough branches or being resistant to branching can sap productivity and keep you from using Surround SCM to its fullest. The following guidelines can help you to achieve a balanced branching structure. See also Branching strategies.

[edit] Use repositories for storage and branches for parallel development

After you set up your repository structure on the mainline, use branching to control releases or parallel development. Do not create repositories when you mean to create a branch. For example, when you are ready to release a product and start development on a new version, do not create a repository for the release code. Create a branch.

[edit] Branch by purpose

There are several branching models including branch by release and branch by bug number. These two models are somewhat arbitrary and can cause unnecessary branches. When choosing a branching model, remember that when you create a branch you are committing to maintaining it for the life of your SCM solution. If you create a branch for every bug fix, you will be managing those branches for as long as you use Surround SCM. While you can hide unused branches, they still exist.

While the ideal branching model will depend on your specific business needs, we recommend using a branch by purpose model for the vast majority of Surround SCM users. In this model, you create a branch when you need to provide the software to groups outside of the development team. Therefore, you would create a branch for alpha testing or for a product release, but not for bug fixes. Branching by purpose also supports creating a branch for research and development. You can create a branch for a group of programmers to use when evaluating large overhauls to the software without affecting the stable code base. This screenshot shows an example of branching by purpose.

After all of the features for WysiCalc are complete, WysiCorp creates the WysiCalc 1.0.x branch. Some developers continue working on the WysiCalc 1.0.x branch, fixing bugs and preparing for release, while other developers work on the mainline developing the next version of the software. When the code is ready for testing, the configuration manager creates the WysiCalc 1.0.0 beta branch to document the build that was tested. The developers working on the WysiCalc 1.0.x branch can fix bug uncovered during beta testing and promote them to the mainline branch so the developers working on the next release can incorporate them into the latest code. When the code is ready for release, the configuration manager creates the WysiCalc 1.0.0 Final Release branch. They can continue performing maintenance on the WysiCalc 1.0.x branch based on production level defects and create maintenance releases without affecting the parallel development of version 2.0.

[edit] Branch late

Branching late goes hand-in-hand with branching by purpose. You will notice that in the branch by purpose model, developers work on the mainline until it is time to provide code to another group. In the previous example, developers worked on the mainline until alpha testing started and the WysiCalc 1.0.x branch was created.

Branching late also reduces the number of merges that have to be performed. Suppose that in the previous example, instead of continuing to work on the mainline to develop WysiCalc version 2 the developers created a new branch for WysiCalc 2.0.x as soon as the WysiCalc 1.0.x branch was created.

In this case, they will have to integrate changes from two branches into the mainline from the beginning of development on version 2. By branching late, they only need to integrate changes from one branch into the mainline until they are ready to begin testing version 2. This greatly simplifies the merge process.

[edit] Use the correct type of branch

Surround SCM includes the following types of branches:

  • Mainline
  • Baseline
  • Workspace
  • Snapshot

Mainline branch

A mainline branch is the top-level branch that contains all source files, other branches, and repositories. For most companies, one mainline branch is sufficient. If there is any possibility that you will need to share files between repositories or branches use a single mainline.

Baseline branch

A baseline branch is a public branch used for collaborative development. Allowing check outs on a baseline branch enables all users to check out and make changes to the baseline code directly. Changes made to files in the baseline branch affect everyone who accesses that branch.

Workspace branch

A workspace branch is a private branch that tracks changes made by an individual user. Users can create their own workspace branch, and other users are not affected by any changes that are made in these private workspace branches. Workspace branches are sandboxes where developers can experiment and perform research and development without fear of adversely affecting the code line. Use workspace branches for features that will be developed by a single individual.

Snapshot branch

A snapshot branch is a static branch that generally corresponds to a project milestone, such as a QA build or final release. Most Surround SCM commands are disabled in snapshot branches. You cannot check out, check in, or merge files into a snapshot branch. Create a snapshot branch when you need to capture the state of the files and the repository structure at a moment in time. You can create a snapshot branch based on the latest file version, a label, or a timestamp.

[edit] Create a branching policy

If more than one user will be creating branches, you should develop a branching policy. Remember that creating a branch is a commitment to maintain that branch for the life of your SCM solution. You do not want to get stuck maintaining branches that were created on a whim.

Your branching policy should specify when to branch, how to name branches, how to document branches, who can create branches, and your sharing strategy. As a general rule, project managers and release managers should be able to create baseline branches. Developers should be able create their own workspace branches. Store the branching policy document in the top-level repository on the mainline branch so developers can access it. Also, add a trigger that emails the developers anytime changes to the policy document are checked in.

Surround SCM supports intuitive branch names and comments. Use the comments to specify the purpose of the branch, when changes should be checked in or out, when changes should be promoted and merged, and who owns the branch. As the number of branches grows, defining branch ownership can help developers sort out issues and avoid confusion. View an example of a well-documented branch.

[edit] Add new repositories to the mainline

When you set up Surround SCM or add files for a new project or product, add the repository and files to the mainline branch. This keeps the original source code on the mainline and allows you to implement branches for specific development purposes from the mainline. Develop on the mainline until there is a need to create a branch.

After you have established branches, it is best to add new files and repositories to the mainline and rebase to propagate the new files and repositories to the other branches.

[edit] Promoting branches

Promoting is the process of updating an ancestor branch with changes made in a selected branch. Promoting merges changes from the child branch up to the parent branch, ensuring that the ancestor branch includes the most current files and that other users have access to your changes. In general, the process resembles the following.

At the feature freeze milestone, which is when feature development for the next release of WysiCalc is complete, WysiCorp creates a baseline branch called WysiCalc 1.0.x from the WysiCalc repository on the mainline.

Feature development for the next major release continues in the WysiCorp Products mainline branch while other developers fix defects in the WysiCalc 1.0.x branch. A code freeze branch named WysiCalc 1.0.0 is created after deciding that WysiCalc is ready for release. Critical defect fixes for the release are made in the WysiCalc 1.0.0 code freeze branch and promoted to both the WysiCalc 1.0.x and WysiCorp Products branches.

Promote changes regularly to be sure that the latest fixes are available on the mainline. Define the promotion policy as part of the branching policies document.

[edit] Triggers

You can use triggers to automatically run a script before or after a specific event. Triggers can be used for notifications, validation, custom text entry, logging, and synchronization.

[edit] Pre-event triggers

Pre-event triggers run after a client requests that a command be performed but before the event is complete. These trigger types let a server script perform additional checks on a file before the event completes. Pre-event triggers are used for validation and custom text entry such as keyword expansion. For example, you can create scripts to verify that text, such as a copyright, is included in specific files when they are checked in.

Use pre-event triggers with caution. Pre-event triggers can cause processing delays especially if they are applied to an entire branch or repository. Pre-event triggers, which are run once per file, can cause performance issues because the Surround SCM Server waits for the script to complete before moving to the next file. Even a one second pre-event script will significantly slow down the server since it takes an additional second per file that the trigger fires on.

[edit] Post-event triggers

Post-event triggers run after a command is successfully completed on the server. These triggers can either run a script or send email. Post-event triggers are for logging, notification, and synchronization. For example, you can create scripts for custom logging of SCM file activity. Email triggers use a standard email template that can be customized to inform selected users when an event occurs to a file or a set of files. Each email template is stored with the trigger on the server. Post-event triggers should always be used unless the trigger is used for validation.

[edit] Provide the proper server access

Triggers are performed on the server; therefore, the scripts that they execute must also be stored on the server. Also, make sure that the processes the trigger calls have the proper server permissions to run correctly.

[edit] Check in/check out and merging

[edit] Include detailed comments on check in

Surround SCM provides space for entering comments when checking a file in. Your changes and the logic behind them might be crystal clear now, but will you be able to interpret the updates two months from now when you are in the middle of another fix? If you have trouble deciphering you own changes, imagine how difficult it is for someone else to interpret your work. Providing detailed notes saves time and improves efficiency because you and your co-workers spend less time figuring out what happened with the last changes and more time working on the current issue.

When checking a file in, it is a good idea to include the following:

  • The original cause for the change (bug or enhancement)
  • The bug or defect number fixed
  • The intention of the change
  • The methodology used to fix the bug or create the enhancement and any other alternatives you considered

To require users to enter a comment when checking in files (and for other activities as well) set the minimum comment length in the server options to a value other than zero.

[edit] Use changelists

A changelist, which is a list of files and the actions to be performed on those files, groups transactions together and treats the files as one unit. Changelists provide an easy way to track the files that were changed to fix a defect.

Changelists implement atomic transactions-if one action in a changelist fails, the entire operation is cancelled and changes are not made to the database. Users can also view the history of changelists and see which files were processed together.

You can add files to a changelist when you add a file, check in a file, create a repository, remove a file or repository, or rename file or repository.

[edit] Check in frequently

Regardless of the type of check outs you use (exclusive or multi-user), check your files in whenever you are able to successfully build with the changes. This practice has several benefits. If you are using multi-user check outs, the necessity to merge is more frequent. Checking in regularly (daily or weekly) reduces the complexity of these merges, and therefore, makes it easier to resolve conflicts. Checking in often also allows you to gain access to the changes created by other developers and prevents surprises later in development.

[edit] Create a check out/check in policy

Like the branching policy, a check in/check out policy helps to ensure that developers are working as efficiently as possible. Your check out/check in policy should specify the following:

  • When developers should use exclusive or a non-exclusive check outs
  • How often to check files back in
  • Who is responsible for performing merges (individual developers, lead developers, project manager, etc.)

Keep this policy in the mainline and root repository and create a trigger that emails all the developers anytime there is a change to the document.

[edit] Administration

[edit] Set proper file level permissions

Unlike other SCM solutions such as Visual SourceSafe, Surround SCM users do not need read and write access to the Surround SCM database directory. Only the Surround SCM server requires read/write access to the database directory. All access rights are controlled through the Surround SCM client. This adds an additional level of security and prevents users from making changes directly to files using a third-party editor and bypassing version control.

[edit] Configure caching to improve performance

Over time, the number of branches in Surround SCM will increase. By default, Surround SCM will retrieve all the branch and repository information for all the branches automatically when you start the server. This may not be an issue when you only have a dozen branches, but as the number of branches grows, it can slow performance if you retrieve all the branch information initially. You will not access all the branches with the same regularity. There will be branches that developers access everyday and others that are essentially archives.

To improve performance, set branches that are accessed less often to Cache on Demand. When a branch uses this setting, the Surround SCM server will only retrieve the details of the branch when a user selects the branch instead of loading it as soon as the server starts.

[edit] Follow the recommended hardware configurations

To avoid performance issues, follow the recommended hardware configurations specified in the Surround SCM Server Application System Recommendations knowledgebase article.

[edit] Perform regular backups

Even with proactive security measures in place, you should still back up your data on a regular basis. Nightly backups ensure that in the event of a virus attack, hardware failure, or malicious activity, your data loss will be minimal. The location of the server database files will depend on where you installed the Surround SCM Server, but the following directories are the default locations:


C:\Program Files\Seapine\Surround SCM\SCMServDb

Mac OS X



/var/lib/Surround SCM/SCMServDb



Issue Management Software | Source Code Control Software | Test Case Management | Requirements Management Software