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.
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.
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).
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.
See the Release a project section below for more information.
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 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).
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.
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.
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.
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 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.
See the Projects panel for related information on working with project files.
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.
- The Update command opens the Merge Project dialog, which offers the choice of retaining the local project version (
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.
- 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.
See the Projects panel for related information on working with project files.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.