Project Management in CircuitMaker

Parent article: Exploring CircuitMaker

True to the community-based principles of CircuitMaker, your design projects and those of the other CircuitMaker designers are collectively stored and accessible from the cloud-based Community Vault.

The Altium Community Vault delivers a robust storage repository for both your designs and their associated configuration, with the benefit of inherent lifecycle and version controlled capabilities happening behind the scenes. From your perspective, design projects are accessed and managed through a simple browser-style interface within CircuitMaker.

The interface into the vault is predominately from the CircuitMaker Home page, where existing design projects (including your own) can be searched, previewed, commented on and ultimately, opened to create a new version. Click the Start  button on the main ribbon menu to open the Home page and its associated Tasks.

Community projects

To inspect or open a CircuitMaker Community project, select Open Project from the Tasks list on the Home page or from the main File menu (File | Open Project).

The project listing on the Community Projects page can be configured to display just your own projects (My Projects) or those designated as Featured or New. Use the projects search box to locate a specific project by name.


The Community Projects list showing the list of Featured projects.

Select a project title to show a preview of its documents and further information. The selections available above the title provide a list of the released versions of the project (RELEASES), its incremental history of changes (HISTORY) and the access rights of project team participants (TEAM).


Select a project in the list to access its history and release details, or open it in CircuitMaker.

If a project has been Released by its owner, the RELEASES view will show the sequence of released versions, or 'revisions', defined by a simple naming scheme. Select a release name to see a list of its constituent documents, which can be downloaded as a single zip file from the button.

The Projects page also allows a public comment to be added for that project, along with a rating. Click the button to apply a personal rating and comment, and the button to toggle the project's watched status.

A project you nominate as Watched will be listed in the Popular, new and watched projects list, available on the Start page (Home | Start). When a Watched project is updated, by any user, an alert email will be sent to your registered email account.

Click the button on the project page to load the project and its constituent documents (Schematic, PCB etc) in CircuitMaker. When a project is opened, the design files are cached locally on your machine (‘checked out’ in version control terms) and thereby added to your Recent Projects list – available in the Tasks list on the Home | Start page.

Community Projects, with the exception of those you have created or any you have Team access rights to, are read-only and any edits you make cannot be saved.

In CircuitMaker there are essentially three ways you can work on projects:

  • By Forking or branching an existing Community project to create new version that's assigned to you.
  • By creating a new Community project from scratch and then adding Schematic and PCB layouts as required.
  • By becoming a member of a design Team that collectively works on a nominated Community project.

Perhaps the simplest way to begin working with CircuitMaker projects is to open and inspect a number of existing Community projects, then create a fork (new branch) of a project that interests you or suits your needs.

Fork to a new Version

A CircuitMaker project in the Community Vault can be freely added to or edited by any member of the design community when it has been Forked from the source version to a new version. The version in a new branch is initially a replica of the source project version, and once edited and committed is 'owned' by the new author.

To create a Forked version of an existing project, click its button to open the new version in CircuitMaker – note that the button also indicates the number of times a project has already been forked.


A project is Forked to create a new version branch while leaving the source version, and its subsequent revisions, intact. Design work on a forked version can also continue as a series of revisions.

A Forked project cannot be 're-forked'. If a project has been forked from another project, this is indicated by the forked from [project name] statement positioned immediately below its name;

The newly forked version of the project can now be opened and edited as your own version of the source project, and also developed through subsequent revisions as your 'branch' of the original project.

Proceed with the edits, as outlined in the CircuitMaker design tutorial.

Note that when the new project version files are Saved once the edit is complete, only the local cached version is updated. This is indicated in the Projects panel, where the project and documents are shown as 'Modified' or 'Scheduled for addition' for new documents.

The indicated file status is relative to the vault version of the project, which will be updated (synchronized) when the local project is Committed – Project | Commit Project. Any new or edited documents are added into the community vault (checked back in as a unique entity) when the project is Committed (see the Version Control information below).


Committing a project to the Community Vault creates a new version in the vault that matches the version you have saved locally.

Projects stored in the Community Vault are version controlled by default, and can be collaboratively worked upon without having to worry about SVN (subversion) services, mutual storage locations or file conflicts. The design collaboration process is as simple as opening a project for editing, while if need be, communicating with other designers through the Comments system.

See Working with Version Control below for more detailed information on version control in CircuitMaker.

Your own projects

To create and store your own unique project in CircuitMaker, simply click the New Project option from the task list on the Home page – View | Start or Home | Start. Enter a project name and description in the Add Project dialog.

CircuitMaker offers the choice of creating a new Public or Sandbox project, where the distinction is:

  • Public project – Creates a project entry in the  Community Vault that is accessible to all users. The shared community project is configured as read-only (cannot to edited), so other users can inspect, comment on, open and Fork the project. If subsequently configured as a Team project, the team members that you nominate have editing rights to the project.
  • Sandbox project – Creates a project entry in the  Community Vault that is only visible and accessible by you. As a 'private' project, you can freely develop the design without it being exposed to other users, then promote it to Public status when you are ready to share the project. CircuitMaker allows for two Sandbox projects.

Note that the project name, description and public/sandbox status can be edited at a later date via the project button, or the project deleted with the  button – both are available in the project preview page.

When the a project has been created it will be automatically added to the Community Vault, included in the My Projects listing and shown as a preview on the Community Projects page. Use the button to load the new project in CircuitMaker.

Schematic and PCB documents can then be added, edited and saved to create your complete design – open the Projects panel (View | Projects) to see the structure and status of your project documents.


A new project is automatically committed to the vault, whereas new Schematic and PCB files will not be publicly visible until committed.

Your project and its documents will become part of the community design pool once Committed to the Vault.

See From Idea to Manufacture - Driving a PCB Design through CircuitMaker for guide to creating design projects in CircuitMaker.

Working with Version Control

The Altium Community Vault acts as a centralized repository for CircuitMaker projects and includes intelligent version control capabilities. This not only stores the collective projects for the CircuitMaker community but also manages access to the design projects and documents for all users. In turn, this enables safe and easy project collaboration between designers, resulting in a collective benefit for members of the CircuitMaker community.

To successfully develop your own projects, and in particular any projects developed collaboratively as a Team, you need to be familiar with a basic concepts of version control and how this is applied in the CircuitMaker and the Community Vault.

The basics

Version control, as the name implies, manages versions of CircuitMaker projects and their documents. A version of a project exists in the Community Vault (the ‘master’ version, in effect), and a replica version will exist when the project is opened in CircuitMaker (held in the local cache repository on your machine).

As you work on and save the project files in CircuitMaker, the local version will no longer match that in the remote Vault. This version difference is resolved when the project is Committed to the vault (copied back and stored as a new version). However, since more than one user can open and edit a given project, multiple versions of that project can exist at any one time, held locally on each CircuitMaker user’s machine – different versions that need to be resolved to a single, latest version in the Vault.


The Community Vault's automated Version Control system continuously monitors and manages projects that have been checked out (opened) in CircuitMaker.

Version control manages these different versions by taking control of how project files are stored in the Vault (as a series of chronological versions), keeping track of who is editing a project, alerting users to the project’s version status and preventing file saving (Committing) clashes between multiple users.

While traditional Version Control (such as subversion; SVN) is largely a manual process, the dedicated version control implemented in CircuitMaker and the Community Vault automates the process as a series of logical steps, while guiding users to the appropriate action where required.

Project file management

The essential concept to keep in mind when working with CircuitMaker is how the centralized version control system continuously monitors the relative difference between the local cached project files and their counterparts in the Community Vault.  

In response to information exchanged with the version control system, CircuitMaker will take appropriate action and change its available options based on these differences. From a practical user’s perspective, this manifests itself in CircuitMaker through a range of alerts and Projects panel file icons, and changes in the available file management commands.


The Projects panel showing a schematic that has been modified and a schematic that has been newly added to the project.

The version control functionality and its responses can be summarized through the following project file situations.

A project is opened:
  • The project files are checked out of the Community Vault and opened in CircuitMaker, thereby populating the local cache.
  • Since the cache and vault files match, the Projects panel shows all files as 'Not modified' – the icon.
A project is re-opened:
  • The project files already exist in the cache, and are opened by CircuitMaker.
  • The version control system checks if those files match their counterparts in the vault:
    • if a file in the cache matches its equivalent in the vault, it is flagged as ‘Not modified’ – the icon.
    • if a file in the cache is newer than the file in the vault, it is flagged as ‘Modified’ – the icon.
    • if a file in the cache is older than the vault version, the project flagged as ‘Out of date’ – the icon.
A file is edited and saved:
  • The local cache is updated with the edited version of the file when it is saved.
  • Since the cache file is now a newer version than its vault equivalent, it is marked as 'Modified' – the icon.
A new file is added to the project:
  • When the new file is saved, it is added to the local cache.
  • The version control notes that the file is not present in the vault, and marks the file as 'Scheduled for addition' – the icon.
A project is Committed:
  • The locally cached project and files are added to the Community Vault as a new version of the project.
    • Differences between the local version of the project (in the cache) and the previous vault version of the project will be resolved in the new version, through file updates and additions.
  • The local and vault file versions are now synchronized (they match) and marked as 'Not modified' – the icon.
     
Hover the mouse pointer over a version control icon to see its meaning.

Collaborative design management

When multiple CircuitMaker designers are working on a single project in collaboration, the interaction between the each user's version of the project and the its source version in the Community Vault becomes a little more complex. Fortunately, the automated vault version control and its relationship with CircuitMaker makes these potentially calamitous design interactions run smoothly, without the need for manual intervention.

When working collaboratively with other CircuitMaker designers in a Team (see below), the version control functionality and its responses can be summarized through the following project file situations, in addition to the ones outlined above:

Another user has updated the project:
  • The project in the vault has been edited, saved and committed by another user. The vault version is newer than your local version in the cache.
  • Your local version of the project will be marked as ‘out of date’ – the icon. If you attempt to Commit the project, you will be asked to Update the project instead.
  • Use the Update command to change your local version of the project to the new version in the vault, or to keep the version held in the local cache. Right-click on the project name and select Update Project from the context menu, or select Home | Project » Update Project.
    • The Update command opens the Merge Project dialog, which offers the choice of retaining the local project version (Keep working copy version), or adopting the version in the Community Vault (Keep revision version) – choose the appropriate option from the dialog’s User Action drop down menu, or select the option from the Apply for all menu so that it applies to all file entries.
Note: Updating the project by retaining your local version will change it to a ‘Modified’ status, because while now up to date, it still does not match the version in the vault. The project can then be committed to synchronize the vault version with yours, however the other user’s local version will now be out of date.


When your local version of the project is older than the version in the Community Vault, it can be updated to match using the Merge project function.

Another user has edited, but not Committed, the project:
  • The project has been edited and saved locally by another user, but that user has not committed the changed project back in to the Vault.
  • This project state is a pending file conflict situation, since an uncommitted edit exists between users. The situation is detected by the centralized version control, which causes CircuitMaker on your machine to flag the project file(s) as ‘Modified and locked by someone else’ – the icon.
  • In this situation you are not able to Commit or Update the project – it has been 'locked' by the version control. When the other user does Commit the changes to the vault, thereby creating a new version, you can update to that version. This is indicated by the associated project icon subsequently changing to ‘Out of date’ – the icon. Select the Update Project command, and choose the vault revision option in the Merge Project dialog.


Here, the local view shows that the schematic has been edited and saved by another CircuitMaker team user, but the user has not yet committed it to the vault.

       Notes:
  • When updating, if you choose the option to keep the local version of the changed file(s), rather than adopting the new version in the vault, the user-to-user situation will be reversed. In other words, since you now have a modified file (relative to the version in the vault) that has not been committed, the other user’s version of the file will be marked as ‘Modified and locked by another user’ – .
  • Rather than updating the project, if you choose to open a file of contention (marked as ), a dialog will open to warn that the file has been modified by another user. You will be warned of the conflict again if you then attempt to edit and save that file. If you continue, the file will then change to a 'Modified and locked' status for the other user - they will also see the icon.
  • In this case, neither user’s version of the file has been committed, or corresponds to the version in the vault. Whoever commits their version first will dominate, forcing the other user(s) to update to the new version in the vault or continue editing to create and commit their own new version to the vault.

Hover the mouse pointer over the project name, files and icons to see the status and any instruction hints.

 

Working as a Team

Along with the concepts of Forking a Community project to a new version and creating your own projects, CircuitMaker also offers the capability to allow a team of designers to work on one project.

When a CircuitMaker Community project has been configured as a Team project, a number of designated Community members – the Team – are granted editing rights to that project. All team members can open, edit and commit project changes to the Community Vault as a collaborative design effort.

In practice, the member that originally created the project takes control over which Community member are included in the team. When a member is added to the team, the 'team project' becomes editable to that member, rather than being in its normal read-only configuration.

Add a Team Member

To configure one of your projects as a Team project, select the TEAM option on its project page. The TEAM page will show the project's current access rights configuration under ACTIVE PARTICIPANTS, which by default includes yourself with full access, and the CircuitMaker Community (Public) with read-only rights.

Add a new team member by selecting Add Team Member to open the Add New Members dialog, where you can search for and nominate the new member with Editing rights.


Add a new CircuitMaker Community member to your design team by granting them editing rights access to your project, which can then become a team collaboration project.

The new member will then be added to the ACTIVE PARTICIPANTS list on the project TEAM page. An email is sent to the member informing them of their new team status and editing rights for the team project.

Note that a member can be removed from the team, with an added comment informing them of the reason, by selecting the button (Remove All Access Rights).

Team Member request

From the other side of the Team equation, any member of the CircuitMaker Community can submit a request to have editing rights for another designer's project – in effect, this is a request to be part of a Team for that project.

To submit such a request, say for a design project that you can make a valuable contribution to, select Add New Team Request on that project's TEAM page view. This opens the Add New Team Request dialog where you can submit the editing rights request with a relevant comment.


Submit an editing rights access request to the owner (source designer) of a project of interest.

In turn, the owner of the project will receive an access rights request email and notification via an entry on the CircuitMaker Activity stream list.


All relevant CircuitMaker project events (including editing rights requests) are steamed as notifications on the Home | Start page.

It is the project owner's responsibility to accept (or reject) the access rights request from another Community member – in other, words to invite them into to the project Team. The request will appear under the PENDING PARTICIPANTS list in the project page TEAM view, where the project owner can select the Accept or Reject button.


An editing rights request from another user will appear under the project's TEAM – PENDING PARTICIPANTS page view, where it can be accepted of rejected.

When the request is accepted, the new team member will then be listed under ACTIVE PARTICIPANTS, and be granted editing access rights. If the request is rejected, editing access rights will not be granted, and the requesting Community member will be informed by email and through the Status setting in their MY REQUESTS listing.

Release a project

During the course of developing a project there are logical points, or milestones, in its progress where it is ‘released’ as a complete version, ready for fabrication and assembly. These are effectively stages in the project’s lifecycle, where it has reached a state that’s ready to prototype, or is in fact finalized as a production version that can be built by anybody.

CircuitMaker caters for this need with the concept of a Released project.

A released project is a snapshot collection of all files in the project, and includes a choice of generated output files such as schematic/PCB printouts, part lists (BOM), fabrication and assembly files, etc. The files are bundled as a unique Revision of the project, stored as a single ZIP file, and preserved in the Community Vault as a named and date-stamped Revision of the  project.

Normally, a project is compiled, fully validated (free of design rules violations, etc) and Committed before it is Released.

To Release a Revision of your project to the Vault, select Release option from the Project button drop down menu which opens the Project Release dialog. Use the dialog checkboxes to select suitable Output files for this release, which can be authenticated using the Validate button. Use the Release button to complete the process.

Because the project file structure has been changed by the addition of released output files, the version control system will regard the project as modified – it no longer matches that in the vault, as indicated by the  icon. Commit the project to bring the Community Vault version up to date.

Project revisions are accessible from the project RELEASES view – available when a project is selected in the Community Projects list – where a sequence of uniquely-named revisions will be listed as they are generated for the project. Expand an individual revision to see its included design and output files.


Selecting a project Release exposes a list of its constituent files, which can be accessed as a single ZIP file from the Download Files button.

CircuitMaker online Workspace

Registered members of the CircuitMaker Community also have access to a personal online workspace that can be accessed at workspace.circuitmaker.com. You can log in to your workspace at any location using a standard browser for an overview of your Projects and Favorites Library, along with your Account details and message notifications.

When logged in, the main workspace screen duplicates the content of your Home | Start screen in CircuitMaker, and provides additional links to CircuitMaker Blogs, Documentation and Forums.


CircuitMaker's online workspace provide location free access to the CircuitMaker Community, and your Projects and Favorites Library

Select the PROJECTS option to view and search through CircuitMaker Community projects, including your own. A project's page can be opened by clicking on its name, which provides a summary and preview of the project in the same manner as in CircuitMaker itself.

If the host machine you are using has CircuitMaker installed, the project can be opened by clicking on its button in the online workspace.

The first time this occurs, the browser may open an application association dialog so that the action can be associated with CircuitMaker. The nature of the dialog will depend on the current browser, but most will have the option to create a permanent association with CircuitMaker so that the dialog will not intervene in the future.

    
The browser's application association may need to set for CircuitMaker. A typical association dialog for FireFox is shown at the left and one from Internet Explorer on the right.