Collaborative PCB Design

As the saying goes, many hands make light work. One of the long-held dreams of board designers is to be able to have multiple people working on the same board, at the same time. While this task might not seem overly complex to the layman – just take Bob’s routing from that part of the board and bring it into my copy of the board – delivering it requires a mixture of certain key capabilities.

These include:

• A system that allows multiple designer access to the same board design, that they can work on and save their own changes without affecting the work of other designers.
• A mechanism to accurately compare and identify differences between multiple versions of the same board.
• Tools that can be used to resolve differences that are detected, allowing the designer to choose whose changes win.
• Tools that can automatically handle a large number of differences and resolve them without creating conflicts.

There’s another tremendous advantage to working with a design tool that is able to show you differences between different versions of the same board – you can also use this ability to check your own work. Forgotten exactly what you routed before the weekend?, no problems, the PCB Editor's Compare and Merge features can also be used to identify and examine the changes you've made, and even remove them if you want.

How it works

Detecting and resolving differences between 2 documents, or diff’ing and merging as it is more often called, is a mature and well-proven process in the software development world. Because software is written and stored in ASCII documents, that can easily be read and compared by a human or a software application, numerous high-quality and robust 3rd party diff & merge tools are available.

To deliver that ability to board designers, diff & merge capabilities have been built into in Altium Designer’s PCB editor. The PCB editor has a sophisticated differencing engine that can detect the smallest physical difference between 2 boards. The physical difference engine works at a shape comparison level, comparing the shapes found on each layer.

The Compare and Merge features actually has 2 ways of working. The first is a 2-way comparison, used to detect differences between your current board and another version of the board. You can think of this as the Difference mode, it displays its results in a , which essentially shows what it is compared to what it was.

The second way of working is a 3-way comparison, which you use if someone else is also working on the board. Imagine the scenario where both you and your colleague Bob check out a copy of the board from the Version Control repository. You both work on your own copy of the board, placing and routing components. Bob finishes the area of the board he is responsible for, and checks it back into the repository. You would like to examine and incorporate Bob's work into your copy, so how does Altium Designer handle this situation?

To establish exactly what has been changed, and by whom, Altium Designer needs to compare your board to Bob's, and also compare it to the board as it was when you both checked it out of the repository (this version is called the Base). This requires a 3-way comparison - by doing this Altium Designer can understand the sequence of changes, and then gives you tools and commands to merge those changes into your version of the board. Whenever the Collaborate, Compare and Merge panel reports Version Control Status: Merge Required, it means that Altium Designer has detected that someone else has checked their work into the repository since you checked the board out, so you will need to perform a Merge to bring their changes into your version of the board. You can think of this mode as the Merge mode, which Altium Designer displays as a .

The route as it was originally, then after it was modified by you (Designer1) and Bob (Designer 2).

When Designer 1 Clicks to show the merge resolution view, Altium Designer shows the route as done by each designer, as well as tagging the routes to show who has modified them.

The first designer’s merge resolution view.

How you use the Collaborative PCB Design Features

Panel reference: Collaborate, Compare and Merge

Altium Designer’s collaborative PCB design features are accessed and operated through the Collaborate, Compare and Merge panel, click the PCB button at the bottom right of the workspace to display the panel. The Actions section of the panel is used for both control and status of the collaboration features. Once a merge or comparison has been performed the differences are displayed in both the Difference Map in the panel and in the main editing window, as shown in the image below.

Use the panel to get status information and run commands to display any differences.

To manage the display of differences the board is temporarily divided up into cells, the cell reference is displayed when you hover the cursor over the cell in the Difference Map in the panel, and is also displayed in the bottom left corner of the cell in the main editing window. The color of the cell indicates who changed that cell, use the legend in the map for more details. The Difference Map will also include a layer tab for each PCB layer that includes a difference, select the layer and then click on a cell to zoom to that cell in the main editing window. Note that changed objects are highlighted using color or a ghosting effect, the meaning of these is explained below.

The Actions section of the panel includes a number of commands, divided into 3 sections:

• Live Collaboration - use these commands to configure, display and clear .
• Version Control Status - will display commands when you are working with a version controlled board.
• Comparison - use these commands to perform a difference comparison with another board either in version control (Click to show differences against any revision) or not (Click to show differences against any PCB document).

Use the Actions commands to launch comparisons and manage the Live Collaboration features.

Most commands are toggle-type commands, click once to enable them, click again to disable them. One command, Manually mark an intended work area, is different in that once it has been clicked the cursor moves into the main editing window, ready for you to define the region.

Terminology and Status Messages

Term	Definition
Head	The latest revision committed to the version control system.
Base	The revision in the repository that you checked out to be your local Working Copy. Also called the checked out revision.
Working Copy	Local copy of the version controlled document on which editing is performed.
Local changes	Changes made on the Working Copy that have not been committed to version control.
Status : File up to Date	The Base revision is the Head revision and no Local Changes have been made.
Status : Modified	The Base revision is the Head revision and changes have been made the Working Copy. This Status indicates that you were the last one to check-in to the repository, so all differences are local and are a result of your own work.
Status : File Out of Date	The Base revision is older than the Head revision and no changes have been made to the Working Copy. This Status indicates that someone else has checked-in their work since you checked out your copy, but you have not made any changes to your copy. Click on the Bring this document up to date with the head revision action to replace your older copy with the latest copy of the document.
Status : Merge required	The Base revision is older than the Head revision and Local Changes have been made. In other words the document is both Modified and Out of Date. This Status indicates that someone else has checked-in their work since you checked out your copy, and you have also made Local Changes to your copy. This can only be resolved by merging your changes with the other designer's changes.
Resolve	The act of updating the Base revision number to the Head revision number. You must perform a Resolve when the Base is older than the Head, and you want your copy to become the Head. This transforms the Status from Merge Required to Modified.

Performing a Difference Comparison

You’ll perform a difference comparison when you’re the only one working on the board, and you want to check your version against another existing version of the board. That existing version can be a version of the board in the version control repository, or a board on a hard drive.

All comparisons are initiated in the Collaborate, Compare and Merge panel. To perform a difference comparison select one of the following commands to access the reference document, your choices are:

1. Click to show differences against the head revision - to compare your board to the last version that was checked into the repository.
2. Click to show differences against any revision - to compare your board to an older revision in the repository.
3. Click to show differences against any PCB document - to compare your board to a board on the hard drive or network.

How Difference Comparison Results are Displayed

Once a comparison command has been selected, all differences are displayed in the Difference Map. Click on a cell that has differences to jump to that region of the board in the main window. Note that you can change the zoom level used to jump via the Zoom Level button at the bottom of the panel. The lower region of the panel will detail the individual differences in the currently selected cell.

In the main editing window, cells that contains no differences are shaded in translucent white, indicating that there is nothing of interest in this area. If a cell contains differences, then it is not shaded. Switch to single layer mode (Shift+S) to more easily see the differences.

Differences are highlighted using a variety of techniques, including color, shading in white, and ghosting (the object of interest is displayed in a dull, hollow-looking way). The meaning of each is detailed below:

Highlight	Explanation
	Additions - these changes exist in your working copy of the board, but not in the other document.
	Deletions- these changes exist in your working copy of the board, but not in the other document.

Performing a Merge Resolution Comparison

You perform a merge resolution comparison when there are 2 or more people working on the same board. For this to work all designers must have checked out a copy of the board from the same repository. Each designer should also configure the feature, to ensure that they all have maximum awareness of what the other designers are doing.

If the Actions region of the panel reports a Version Control Status:Merge required, then a merge resolution comparison is required. To do this, use the Click to show merge resolution view command in the Actions list.

How Merge Resolution Comparison Differences are Displayed

Highlight	Highlight	Explanation
(zoomed out)	(zoomed in)
		Additions made by you.
		Deletions performed by you.
		Additions performed by someone else.
		Deletions performed by someone else.

Resolving Differences

Differences are resolved by merging in differences detected in the reference document, into the current board. Merging can either be performed in the PCB editor window or in the Collaborate, Compare and Merge panel. The Automatically merge in non-conflicting changes from the head revision command in the panel is displayed when the Show Merge Resolution View is active. It will bring into your working all the non-conflicting modifications made in the head (depicted in the Difference Map by green cells) .

To merge from the panel, right-clicking on a modified cell in the panel’s Difference Map to display the Add/Remove to match [ReferenceDocument] command. Selecting the command will modify the primitives in that cell to match the reference document. Note that the name of the reference document will be displayed in the square brackets. Multiple cells can be highlighted at the same time (shift+click or drag+click to multi-select) allowing as many or as few changes from the reference to be brought across to the current board.

If a cell includes some changes that you want to keep and others that you want to bring in, then you can selectively merge the changes in the main PCB editor. To do that you use the right-click Merge menu.

Right-Click Merge Menu

To resolve differences in the main editing window, right-click on an object that is flagged as a difference. The popup context menu will include a Merge submenu, in that will be merge actions tailored to the primitive that was clicked on, as well as the status of the changes in the cell.

Right-click on a marked track and select a command from the Merge sub-menu.

There are 3 possible levels the commands in the Merge submenu can operate on:

• Primitive - only the actual track segment/via/component that you right-clicked on will be modified by this action.
• Route - for the connection you clicked on, all track segments that are different will be modified by this action.
• Cell - all track segments passing through the cell that are part of this difference, are modified by this action.

The commands available in the right-click Merge sub-menu support the following types of actions:

• Add - Displayed when clicking on a primitive that exist in the reference document, but not in your document. Adds the primitives from the reference document into the current document, but does not remove primitives. When the Add Component action is performed, it will attempt to remove an existing component that would cause an UniqueID conflict.
• Remove - Modifies primitives so the changes made to the current document are removed.
• Replace - Adds and removes primitives so the end result matches the reference document used for comparison.

Live Collaboration

The backbone of Altium Designer's PCB collaboration feature is the version control system and the repository. The VCS keeps track of which revision each designer has checked out, and if it is different from the Head revision.

To make it easier for individual designers to keep track of who else is working on the board you can also use Altium Designer's Live Collaboration and Work Regions features.

The Live Collaboration feature details which other designers are currently working on the same board. The log-in and computer name of each designer that currently has the same board file open (their own local copy) is detailed in the Difference Map region of the Collaborate, Compare and Merge panel.

Collaboration Server Path

For the Live Collaboration feature to work, Altium Designer uses a central file to log collaborator and work region information (WIP.xml). The file is stored in the location defined by the Collaboration Server Path option (PCB Editor - General page of the Preferences dialog). To use this feature each designer must define the same path in their installation of Altium Designer.

Work Regions

Each designer can define Work Regions - areas that define where they are working. Work regions are defined in the main workspace, enable the Click to show work regions in the main editor option in the panel to display them in the main workspace, before you attempt to define one.

To create a work region, click the Manually mark an area as work region command in the panel, position the cursor where one of the corners is to be located, and click to start. Work regions are polygonal objects, click to define each corner of the polygonal shape, Shift+Spacebar to cycle corner modes, Spacebar to toggle the corner direction, right-click to close the shape and end placement.

Note that you must have a common Collaboration Server Path defined to see the work regions that other designers have defined in the same board file.

The Role of Version Control

The challenge of collaborative design has long been solved in the software development domain. Best-practice software development demands that code is developed in a structured and ordered way, with the code broken down into individual files that reflect the overall structure of the project. That means that software development teams produce a large numbers of code files, containing large amounts of code.

To effectively and efficiently work collaboratively across that fileset, software developers typically use a Version Control System. A Version Control System, or VCS, allows them to:

• Easily store all project files in a single, central location, or repository (making it easier to back up).
• Undo changes, including across multiple files.
• Store and retrieve any file from any point in the history of the project's development.
• Work independently, yet collaboratively. Each team member has their own local copy of the files they need, when their development reaches a point of maturity they can check-in their work to the repository.

If you have not worked with a Version Control System then you might be inclined to think, it’s just too much mucking around. In reality, working without a VCS actually leads to far more mucking around, with everyone crafting their own system for saving revisions of files with strange filenames, in special locations, that soon become forgotten. In fact pretty much any business that makes its money developing content in electronic files is well served by storing those files in a Version Control System.

And the overhead of the VCS? Working with a VCS is not hard, once you understand the basics of interfacing to the repository. Whenever you check-in your work you have the opportunity to include a comment, use it well as it is ideal for keeping track of your changes. You can easily review the history of check-ins, examine the comments, or Revert to any version of any file. Once you have checked out a copy of the project into your own local working area you simply work as you always did, just check-in your updates when they are ready to be shared with others. Altium Designer interfaces directly to the repository too, making repository tasks, such as checking in your work, as simple as right-clicking on the file in the Projects panel.

What happens if my Project is not Under Version Control?

Altium Designer’s collaborative PCB design capabilities use a Version Control System at its core, providing the mechanism needed for individual designers to be able to work independently, yet bring their independent efforts together when needed. To fully utilize Altium Designer’s Collaborate, Compare and Merge features each designer must be working on their own copy of the same project, checked-out from the same repository. The reason for this is that the repository is the central pivot point - by communicating with the repository, Altium Designer is able to establish the status of each revision of the board that each designer has checked out, and then offer commands that can be used to compare to detect differences, and then merge those differences if required.

If you are working on a board that is not under version control, you can still use the compare and merge features. In the Actions section of the Collaborate, Compare and Merge panel, use the Click to show differences against any PCB Document command to find differences between the current board and any other board. Note that you will not have access to the Live Collaboration features if the board is not under version control.