Safeguard designs with source control

In this Blog entry I’ll show you how to get started with version control by installing the popular and free Subversion version control engine, and setting up Altium to work with it.

Altium is one of the first electronics design systems to tap into the potential benefits of using document version control for the management of electronic design data. While version control is standard in software-based design, its use in electronics has to date been limited. This is because traditionally version control systems have focused on text-based documents. Managing graphical binary format documents like schematics and PCB files is difficult in such systems. 

Altium changed this by including sophisticated graphical comparison and differencing engines in the design environment, and providing the interfaces necessary to make using a versioning system a natural part of the electronic design process. This allows all designers, from a single contractor right through to large teams, to benefit from the security and robust data management that good version control allows, without wasting resources and time in managing external versioning systems. Everything you need to access the power of version control in built into the Altium Designer interface. All you need is a version control engine installed on your computer.

Download and install Subversion

Subversion is an open-source version control system. It is developed as a project of the Apache Software Foundation, and as such is part of a rich community of developers and users. 

To get started, visit http://subversion.apache.org/ and download and install the latest Subversion binary packages for Windows. 

While not essential, I recommend that you also download TortoiseSVN, a simple Subversion client that you can use to view and maintain the document repositories you will create with Altium Designer. It’s a good tool for troubleshooting and learning about the structure of version control database.

Configure Altium Designer

Once Subversion is installed, we can turn our attention to configuring Altium Designer. 

• Start Altium Designer and open the menu  DXP^™ > Preferences.
• Expand the Version Control branch in the navigation tree and click on General.
• In the dialog, select SVN - Subversion as the provider.
• Click the Auto Detect Subversion button to automatically setup paths to the svn.exe and svnadmin.exe files. 

At this point you will need to shut down and restart Altium for the settings to take effect.

Create your repository

In version control terms a repository is the managed database or folder structure that stores all the documents and change information that is accessed by the version control client. So before you can start putting your Altium projects under version control, you need to create a repository. The repository can be stored on a local hard drive, or an accessible network location. 

• Open Windows Explorer or your file manager of choice and create a folder in which to store the repository – in my case I’ve created the folder C:\repositories\repo1.
• Load a project into Altium and show the project in the Projects panel. This panel can be enabled on the menu: View > Workspace Panels > System > Projects.
• In the Projects panel, right click on your project file (*.PrjPCB) and choose: Version Control >Create Repository.
• Use the folder icon to browse for the empty folder you created, or type the path, such as C:\repositories\repo1, and leave the Repository type option as  Filesystem.
• Click OK, and Altium will instruct Subversion to create the empty repository. 

Subversion repositories use a special file structure, which should not be manipulated manually. Use Altium or TortoiseSVN's Repo-browser if you wish to view the contents of the repository. 

Add the project files to the repository

It’s now time to add the files that make up your project to the repository. 

• In the Projects panel, right-click on your project file (*.PrjPCB) and choose: Version Control >Add Project To Version Control.
• The Local Directory path should already contain the path to your current project – if not, use the dropdown list to select it.
• The Path to Repository uses the Subversion format, so click the '...' button to browse to the repository path.
• In the dialog, set Method to File.
• Set Repository Location to the path to your repository, such as C:\repositories\repo1.
• The Repository Subfolder may be left blank, unless you have created a logical folder within your repository.
• Click the Test button and you should be greeted with Connection OK – if not check all the paths are entered correctly and try again.
• Click OK, and the Path to Repository now contains a path such as file:///C:/repositories/repo1.
• Click OK to exit the dialog.
• The files belonging to your project will now be listed. Select all checkboxes and click OK to complete the operation.

 Note that the above process currently assumes that all project files are contained within the same folder or a subfolder that which contains your .PrjPCB file. If you have added files to your project that are located elsewhere, you’ll get an error when you try to add the project. In this case untick the files that are not stored under the project directory and try again. You can individually add the files that are stored outside the normal folder structure by right-clicking on them in Altium Project panel and selecting Add File to Version Control. New files you add to your project can also be added to version control in this way. 

The Comment box at the bottom of the dialog is presented to you every time a file is added or modified. This is for your information, and is useful when referring to this version of your files later. 

Once all the files are Added and Committed, your project is fully version-controlled!

Managing change

The original files still exist external to the version control repository, and these files act as a "working copy" to allow Altium to open and save them. 

Make some changes to some of the files in your project and save them. Take a look at the Projects panel. The status icon next to each file changes from a green tick to a red explanation mark to indicate the files have been modified and are now different from the latest version stored in the repository. To bring the repository up to date with the latest changes, right-click the modified file in the Project panel and in theVersion Control sub menu, commit the file, or alternatively commit the whole project. Committing is the process of updating the repository to reflect the latest version of a file.

The Storage Manager panel can be used for more flexible control. To open the panel select View >Workspace Panels > System > Storage Manager from the menus. Multiple individual files can be selected by holding Ctrl while left-clicking in the Files section of the Storage Manager. Right-click the selection to commit just those files. 

The time line found in the bottom section of the Storage Manager shows the various revisions of the file history and allows visual comparisons to be loaded. Each revision is displayed, and if you added comments during your file commits, the comments will help you to determine the relevant revisions.

Ctrl+left-click to select the two revisions of interest. Right- click the selection and choose Compare. Altium ’s sophisticated graphical differencing engine shows you both electrical and graphical differences between the two versions of the file, allowing you to easily merge changes between versions.

The TortoiseSVN client

While most day-to-day operations, such as check out and check in or files, can be managed easily and directly from within Altium, there are times when you may want to access the version control repository directly. For example, you may wish to check out your project files to another location or on another system. 

TortoiseSVN is an SVN client, available for download from the Subversion site, that can be used to administer your repositories external to Altium. 

To use TortoiseSVN, open Windows Explorer, right-click the folder containing your repository and chooseTortoiseSVN > Repo-browser. This will launch the browser and automatically set the URL to the folder location, file:///C:/Repositories/repo1/.

Right-click the entry in the left panel and choose Checkout. In the Checkout dialog, browse for the directory where you want your project to be extracted to and made available for editing in Altium.

One note of caution: Subversion repositories can not be edited directly, so do not place other files in the folder, or attempt to edit the files without using either Altium or an SVN client.