Version Control & Design Repositories

One of the greatest strengths of an electronic authoring and editing environment is the ease with which you can create and modify a file. This capability means that ideas can be captured, explored, and matured quickly, but it also means that it can be difficult to keep track of changes made to valuable files such as source code and electronic design data.

The need to keep track of changes made to a file, combined with the need for a systematic solution for managing sources captured in an electronic form, has given rise to Version Control Systems (VCS). Version control systems are software tools that are not only able to maintain a history of the various versions of a file, they also support opening any revision of that file, as well as comparing changes made between any two versions of the file. A VCS will generally integrate with the local Operating System (OS) by providing additional versioning functions and operations for folders and files.

Version Control Systems can be operated completely independently of the authoring and editing environment used to create a file. They typically offer an interface that allows you to Add then Commit files into a central storage area called the repository, a Checkout feature to copy a file from the repository to a working folder, a Commit feature to check back in any changes to the repository, a method of logging information about a change, and much more.

These features are found in Windows shell extensions such as the Tortoise client and are also included in Altium Designer itself. VCS operations can be performed within the Altium Designer environment, without the need to access the OS file system.

Typically a version control system will also handle the situation where a file has been checked out and modified by multiple people, who could then check their changes in on top of each other, potentially losing a designer's work in the latest revision. Dealing with this requires tools to compare versions of the file to detect differences and an interactive tool to merge the differences back into a single version of the file, such as the PCB collaboration capabilities available in Altium Designer.

It is helpful to understand the terminology used with version control systems. Even though there are numerous systems available, they generally all use similar terms to describe their functionality.

Version Control Essentials

The basic approach to working with a Version Control System (VCS) is to access a copy of the project files that you want to work on from a repository, edit the files in Altium Designer and then ‘commit’ the modified files back to the repository. The interaction with the repository is through a version control system interface, which Altium Designer has built into its Storage Manager panel and Projects panel.

The key to how a version control system works is that it monitors the status of files that have been accessed from the repository, via a working folder, and therefore tracks what revision is being worked on and if it has been modified. Although the outcome is the same, the repository and working file arrangements differ between types of version control systems – for Altium Designer, this can be Subversion (SVN) or Git.

Subversion VCS

The figure below illustrates the concept of a Subversion repository that holds a sequence of design file revisions (up to revision 5), with the latest copy checked out (File » Check Out) in a working folder. When the files in the working folder are opened in the Altium Designer environment, Altium Designer recognizes that a project file is under SVN version control, with its current version control status being shown in both the Storage Manager and Projects panel.

Git VCS

The figure below illustrates the concept of a Remote Git repository share that holds a sequence of design file revisions (up to revision 5), where its content has been copied to a local Working Git repository – typically by Cloning the remote repository or Pulling its data into the working repository. When the files in the working repository are opened in the Altium Designer environment, Altium Designer recognizes that a project file is under Git version control, with its current version control status being shown in both the Storage Manager and Projects panel.

In both of the above VCS systems, the link between the source repository and the working location is referenced in the latter’s VCS database (in the .svn or .git system subfolder).

When VCS working files are open in Altium Designer the right-click menu in the Storage Manager panel (and the Projects panel) allows you to perform standard VCS actions, such as committing a changed file to the central repository (SVN) or working repository (Git).

The Commit command registers the updated file in the repository, increments the revision number (stored internally in the VCS), logs a message that you can enter to describe the changes made to the file, and in the case of Subversion, stores the copy of the file in the central repository. In the Git arrangement, the updated file may be copied from the Working repository to the Remote repository at any time using the Push command.

Multiple User Access

In most situations, a company’s Version Control infrastructure will be based on central SVN or Git repositories, served over the network using one of the available protocol methods – svn, svn+ssh, https, etc. This provides access to all users on the network, subject to permissions, and a vehicle for collaborative project development from a single source.

In turn, the multiple access capabilities allow different team members to continue working on a project independently, without having to wait for someone else to check a file back in before they can work on it. A distributed Git version control system takes this advantage one step further by allowing files to be committed to the local working repository as you work, and those committed changes ‘pushed’ back to the central Git repository at any later time – and as such, does not require a network connection until then.

Nevertheless, a team-compatible VCS does require that the tools and techniques are available to resolve the inevitable situation where two users have modified the same file. When these capabilities are available, the foundation is in place for true multi-user design collaboration and its associated benefits.

To support this situation, Altium Designer includes schematic and PCB comparison (or 'diff') capabilities, available through the Storage Manager and Collaborate, Compare and Merge panels. Altium Designer offers sophisticated PCB design collaboration features that allow file merge differences to be viewed and resolved within the editor, to ultimately create a new Head revision in the VCS. The advanced PCB collaboration functionality also allows for live design collaboration between multiple users, with the ability to define and assign sections of a design as user Work Regions.

VCS Repositories

Before using version control, the project files must be recognized by both the VCS and Altium Designer as being under version control. This process can be different for the various VCS methods and applications, but it essentially entails creating and/or connecting to a design repository and adding design project files to that repository.

Design repositories are based on a database structure, and internally store information in a hierarchy of files and directories, referred to as a file tree. The actual repository that you connect can be a central SVN repository, a Git working repository (that is associated with a remote Git repository), or one you have created in an accessible location such as on the local PC or a shared network location.

Depending on the type of repository, it will be accessible via a range of protocols that include:

• Conventional file access, which is usually for local or network-based repositories.
• The svn protocol, using plain text or TCP/IP – or the secure svn+ssh equivalent.
• The http method, generally using WebDAV over http – or the secure https equivalent.

Subversion (SVN) repositories are connected to, and created when necessary, in the Data Management – Design Repositories page of the Preferences dialog.

Connect to an SVN Repository

To connect to an existing SVN design repository, from the Data Management – Design Repositories page of the Preferences dialog click the button, then choose the SVN entry on the associated menu – this opens the SVN Design Repository dialog. This provides Design Repository Properties settings that allow you to define the local name of the repository connection and its target folder path for checked-out design files.

When an existing SVN repository is registered in Altium Designer it allows design files to be included under Subversion version control.

The dialog's Repository options need to be configured to match the available repository's location, an optional subfolder target, and a compatible protocol method for the connection. Note that the svn and http access methods require additional information that relates to the host system and its access credentials.

Create an SVN Repository

To create a local SVN design repository, go to the Data Management – Design Repositories page of the Preferences dialog and use the  button to open the Create SVN Design Repository dialog.

The dialog provides a range of configuration options that allow you to define the repository's folder location and method (connection protocol), and the local connection name and target folder path for checked-out design files. Note that the svn and http access methods require additional information that relates to the host system and its access. For more information, see the above links.

Nominate or create a local folder that will be configured as a named VCS repository.

The installed VCS system will subsequently create the correct version control file structure and database in the nominated repository folder. Once created and registered, the new repository entry will be connected and listed in the Data Management – Design Repositories page of the Preferences dialog. Click or to confirm the changes.

Use an SVN Repository

With the new or existing design repository available to Altium Designer, project design files can be added to and retrieved (checked-out) from the repository using the Storage Manager and Projects panels, and commands from the main menu. As the repository files exist under version control, all design revisions are tracked and accessible from within Altium Designer.

Use the project name right-click context menus in the Storage Manager or Projects panels to add then commit a complete project folder (and its constituent design files) to version control – by choosing the History & Version Control » Add Project Folder to Version Control command and using the subsequent Add to Version Control dialog then choosing the History & Version Control » Commit Whole Project command and using the subsequent Commit to Version Control dialog.

Alternatively, a new project can be added to version control while being created through the Create Project dialog – File » New » Project. Choose Version Control in the Locations list on the left of the dialog, and select the target repository from the registered options in the Repository drop-down menu.

The Local Storage option in the Create Project dialog defines where the working copy of the project is stored. It is these files that are opened and edited in Altium Designer and ultimately committed back to the repository (checked-in) as new revisions when the edits are complete. The working copy of the project can be re-opened for editing using the File » Open Project command, or the File » Recent Projects list.

If required, a fresh instance of the project can be checked out to a new working folder and loaded in Altium Designer using the File » Check Out command, as shown below.

Once a compatible VCS repository is accessible in Altium Designer, design files can be added to and then checked out from the repository.

Connected Workspace VCS

The most advanced form of working with projects under version control is to harness the capabilities of a connected Workspace. A Workspace offers the advanced construct of a project, which offers a simplified workflow and storage, enhanced collaboration capabilities, and more.

The target VCS repository in a Workspace is tightly integrated with both the Workspace and Altium Designer (when signed in), which eliminates the need to set up and configure separate VCS repositories. User access, the repository content, and the status of projects can be managed through the Workspace browser interface.

References

• Version Control Terminology
• SVN website: http://subversion.apache.org/
• SVN online manual: http://svnbook.red-bean.com/
• SharpSVN project home: https://sharpsvn.open.collab.net
• Git website: https://git-scm.com/
• Git online documentation: https://git-scm.com/doc
• The Tortoise Clients: http://tortoisesvn.net and https://tortoisegit.org/
• Source Control How-to, by Eric Sink: http://www.ericsink.com/scm/source_control.html