Cloud repository (SVN) for Altium Designer using Assembla – Tutorial

Introduction

If you are a small company or a contractor using Altium Designer, you should consider using a cloud repository (shortened “repo”). There are three main advantages:

1. Your precious designs are backed-up and secured off-site. You do not depend on local backups, and you don’t need to maintain your own server.
2. You can work from anywhere. If you have a floating license, you can install Altium on multiple machines, and move between them effortlessly.
3. You can very easily collaborate with colleagues, contractors, board reviewers, or other employees either on- or off-site.

We have been using this solution for a few months now and we couldn’t be happier. Setup effort is minimal, the costs are very reasonable, and our work has gotten tremendously more efficient and robust, so I wanted to share this with the community.

We utilize Altium’s built-in SVN (Subversion) so no additional installations are needed.

You will need an account with a cloud version control service provider. Using https method of connection seem preferable. We have been using Assembla and it works great, but other service providers are also available.

Altium provides a detailed tutorial on version control here. We strongly recommend that you familiarize yourself with Altium capabilities and limitations. If you have no experience with version control, here is a quick general workflow:

1. First, a locally stored project is added to version control by user A.
2. Then, User A commits (uploads) the project to repo.
3. Once in repo, the project can be checked-out (downloaded) onto any number of machines, for example user B and user C.
4. Now, there are multiple copies of the project – one in repo, and one locally on every machine that checked-out the project.
5. Any work in Altium on the project, will always be saved to a local copy. For example, user B made changes to schematic and layout.
6. User B can then push the changes to repo copy, by committing to repo.
7. Now users A and C have an outdated copy of the project. They can update their local copy from repo copy.
8. If two users A,B worked simultaneously on the same project, user A can commit to repo, and user B will have to resolve any conflict between two versions. Such scenario is better avoided by allowing only one user to work on a project at any given time, or declaring which files each user is allowed to update (user A works on schematics, user B works on layout, etc)

Assembla Setup

1. When signing up with Assembla, ‘Organization Domain’ will create a portfolio. For example, portfolio mycompany will provide access to repositories through the url: mycompany.assembla.com
   NOTE: portfolio name cannot be changed, so use a general, short, and simple name.
2. Create at least one space. each space is a separate repository. To start, create space myrepo1 or your choice of a name
   
3. Within space myrepo1 add SVN Repo

Altium setup:

1. Go to Preferences –> Data Management –> Version Control. Verify that “SVN- Subversion” is enabled.

1. Go to Preferences –> Design Repositories. Hit “Connect To” and choose SVN from drop-down menu.
2. Fill in the following details:
   • Name (recommended): mycompany-myrepo1
   • Default Checkout Path: this is where projects are downloaded (“checked-out”) to, from the cloud. For example:  D:\Altium\AD18\RepoWorkFolder
   • Method: https
   • Server: subversion.assembla.com
   • Server Port: Default
   • Repository Subfolder: /svn/mycompany^myrepo1
   • Username: (Assembla credentials)
   • Password: (Assembla credentials)

• Hit ‘Test’ and verify ‘Connection OK’

Add a project to version control / repo:

1. Right-click on a project in Projects toolbar. Go to Version Control –> Add Project Folder to Version Control…
2. Choose repository myrepo1
   
3. Create new folder; by default, the newly-created folder will have the same name as the project. I find this convention very convenient
   
4. For beginners, you can use the default selection that Alium presents. As you will see later, this includes by default all major design files.
   
5. Little blue + signs will appear in project explorer
   

Commit

(initial upload of project, or commit project changes to repo)

1. Right-click on a project in Projects toolbar. Go to Version Control –> Commit Whole Project…
   
2. Add commits comments. This is not mandatory but I highly recommend to add meaningful information that can help keep track of commits later on.
   
3. Little green Vs will appear in project explorer
   

Check-out

(download) a project from repo:

1. Go to File –> Check Out…
   
2. Choose repo yourrepo1 to check-out from.
3. Choose a project folder
4. Hit OK.
5. Project folder will be downloaded and the project will automatically be added to the environment. A green V mark next to the project indicated that local copy is identical to repo copy.
   
6. Note: from now on, any changes to any part of the project will be saved locally. For example, is .SchDoc was changed, this will show in project explorer:
   

Update

(update local project with repo changes)

Use Update when repo copy of the project is newer then local copy of the project. This happens regularly when a group of people collaborate on a project. Whenever one member commits their changes to repo, all other members’ local copies are outdated and needs to be updated.

1. Right-click on a project in Projects toolbar. Go to Version Control –> Update Whole Project
2. If changes have been made to local copy of the project, Altium will ask whether to discard changes (by overwriting with update), or cancel update in order to resolve conflicts.

Notes, and advanced topics

1. This tutorial was written using AD18, but I can confirm that everything works identically with AD17. I see no reason why it won’t work with older versions, but I didn’t try.
2. We use multiple repositories for different purposes:
   1. Separate repository for various users, if you you want to limit their exposure only to specific projects, versus the entire content of your repo.
   2. I personally use a “handsoff” repo, where I commit the designs that I spun, to guarantee that those will always serve as an accurate representation of exactly what was manufactured. Once a design was put into handsoff repo I regard it as locked – and I don’t allow any more commits.
3. In order to move projects between different repos, all you need to do is delete the hidden subfolder folder .svn within the project folder
   
4. There are several other features that have not been discussed here, such as locking, resolving conflicts, and comparing designs.
5. It is recommended that all parties that collaborate on one project, be very explicit who “owns” the design at every given time, so there are no conflicts. It is also possible to have different members working on different parts of the project. For example, one person can work on libraries (verifying and updating footprints and symbols, 3D bodies, etc.) while another person works on layout and schematics. Library synchronization can be completed after the design is “owned” again by one person.
6. If there’s a need to remove a folder from version control, it can be done only through command-line, and not through web interface. The process is not too complicated, please let me know if you struggle.

Any comment you may have on this tutorial: corrections, edits, feedback, request of anything else really, please let me know. I’ll be more than happy for any opportunity to make this tutorial better.