Version Control & Design Repositories

Now reading version 1.0. For the latest, read: Version Control & Design Repositories for version 4

Nexus message

This documentation page references Altium NEXUS/NEXUS Client (part of the deployed NEXUS solution), which has been discontinued. All your PCB design, data management and collaboration needs can now be delivered by Altium Designer and a connected Altium 365 Workspace. Check out the FAQs page for more information.

 

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 source 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 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 NEXUS itself. VCS operations can be performed within the Altium NEXUS 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 the PCB collaboration capabilities available in Altium NEXUS.

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 NEXUS and then ‘commit’ the modified files back to the repository.  The interaction with the repository is through a version control system interface, which Altium NEXUS 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 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 NEXUS, 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 NEXUS environment, Altium NEXUS 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 NEXUS environment, Altium NEXUS 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.
► See Add To Git Version Control and Clone a Git repository for more information.

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).

► See Using Version Control for more information on working with SVN and Git version control systems in Altium NEXUS.

When VCS working files are open in Altium NEXUS 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 respository (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.

The Altium NEXUS Version Control interface can be accessed directly from the Projects panel or from the Storage Manager panel, where more options are available.
The Altium NEXUS Version Control interface can be accessed directly from the Projects panel or from the Storage Manager panel, where more options are available.

Both the SVN and Git version control capabilities that are available in Altium NEXUS are enabled by their respective ExtensionsVCS Provider - SVN and VCS Provider - Git. These are installed by default and may be accessed through the software’s Extension & Updates view.

Multiple user access

In most situations a company’s Version Control infrastructure will be based on central server-based 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 server-based permissions, and a vehicle for collaborative project development from a single managed source.

In turn, the multiple access capabilities allows 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 centralized 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 NEXUS includes schematic and PCB comparison (or 'diff') capabilities, available through the Storage Manager and Collaborate, Compare and Merge panels. Altium NEXUS 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.

► See Using Version Control for a guide to applying version control to project design in Altium NEXUS.

VCS Repositories

Before using version control, the project files must be recognized by both the VCS and Altium NEXUS 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 to a server-based repository, using plain text or TCP/IP – or the secure svn+ssh equivalent.
  • The http method to a server-based repository, 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.

  • Git type repositories are created outside of Altium NEXUS, and the content of a local working Git repository is accessed by opening files from its host folder.
  • The management of both remote and local working Git repositories is typically through company systems and external Git tools, while file level operations (Commit, Push, Update etc) are handled in the Altium NEXUS editing environment.
  • The management of repositories is handled automatically when using Managed Projects in an Altium managed content server.

Connect to a 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 from 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 NEXUS it allows design files to be included under Subversion version control.
When an existing SVN repository is registered in Altium NEXUS 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 server and its access credentials.

This connection process is not required for a repository that is available in (has been added to) an Altium managed content server. Altium NEXUS will automatically connect to the server-hosted SVN/Git repository(s) when a user signs in to that server. See Accessing a Server from Altium NEXUS.

For more information, see:
► The Data Management – Design Repositories page of the Preferences dialog.
► The SVN Design Repository dialog page.

Create a 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 server 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.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.

The process of creating a VCS repository – traditionally completed using an external (separate) VCS client – can be  done directly in the Altium NEXUS Preferences dialog.
The process of creating a VCS repository – traditionally completed using an external (separate) VCS client – can be  done directly in the Altium NEXUS Preferences dialog.

Use a SVN Repository

With the new or existing design repository available to Altium NEXUS, 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 NEXUS.

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 – Version Control » Add Project Folder to Version Control.

 

Alternatively, a new project can be added to version control while being created through the New Project dialog – File » New » Project » Project. Choose VCS as the Project Kind and select the target respository from the registered options in the Repository drop down menu.

The design files under version control in the repository can be subsequently checked out and loaded in Altium NEXUS using the File » Check Out command, and ultimately Committed back to the repository (checked in) as new revisions when the edits are complete.

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

Altium Managed Content Server VCS

Most advanced form of working with projects under version control is to harness the capabilities of an Altium managed content server, such as an Altium NEXUS Server. The server offers the advanced construct of a Managed Project, which offers a simplified workflow, full lifecycle management, enhanced collaboration capabilities and more.

The target VCS repository in a managed content server is tightly integrated with both the server and Altium NEXUS (when signed in), which eliminates the need to setup and configure separate VCS repositories. User/Group access, the repository content and the status of projects can be managed through the server browser interface. In Altium NEXUS, projects are managed in the Explorer panel and the usual VCS commands are available in the Projects and Storage Manager panels.

For more information see:
Managed Projects and Releasing a Design
Working with a Managed Content Server

Additional information

Version Control Terminology

References

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.
Content