Management of Projects from within Altium Designer
Parent page: Managed Projects
This document takes a look at working with managed projects from within Altium Designer, including:
- Creating a project - either directly or by making an existing, unmanaged project available online.
- Sharing a project - changing the access permissions for a project so that users that need to see and work with it have the ability to do so.
- Opening a project - to be able to work on it.
- Cloning a project - to quickly get an identical copy without having to build the project from scratch, which is great if your next project is very similar.
Creating a New Managed Project
There are two ways in which a managed project can be created from within Altium Designer:
- Creation of a new project through the Create Project dialog.
- Making an existing, non-managed project (regular project, or a project currently under version control) available to the Workspace - essentially 'registering' the project with the Workspace and creating a 'mirror' of it.
The following sections take a closer look at these two avenues of creation.
Through the Create Project Dialog
A new managed project can be created from within Altium Designer using the Create Project dialog (File » New » Project):
- In the Locations list, select the entry for your Workspace (it will appear with the name defined for it) - you must be actively connected to the Workspace to see this option in the listing. This will be the target server in which to store your new managed project.
- In the Project Type list, choose the type of project you wish to create, and choosing from the applicable templates available as required. If you have project templates created and released into your Workspace, these will appear listed as the only available templates from which to choose.
- Enter a Project Name and optionally, a project Description.
The Create Project dialog includes further options:
- Check the Enable Formal Version Control option (the default) to impose all VCS capabilities on the project, such as Revisions and advanced sharing capabilities. When unchecked, the project is simply stored in the Workspace for basic shared access. More information.
- Click the Advanced control to specify folder paths.
- Use the Folder field to specify where the folder for the project - within the Workspace's folder structure - is to be created. The default path for new projects is specified on the Admin - Settings - Projects page of the Workspace's browser interface (by default, this will be
Projects\<ProjectName>
). Click the button to browse to and select a different server folder, if required. - Use the Local Storage field to specify where the project will be stored on your hard drive, prior to its committal to the centralized design repository. The default location is defined on the System - Default Locations page of the Preferences dialog. Click the button to browse to and select a different folder location, if required. This is the 'working' folder for the project and the local Git repository it is committed to. The project is ultimately, or at the time of committal, Pushed to the centralized design repository in the Workspace (Versioned Storage), which is the remote Git repository.
- Use the Folder field to specify where the folder for the project - within the Workspace's folder structure - is to be created. The default path for new projects is specified on the Admin - Settings - Projects page of the Workspace's browser interface (by default, this will be
- Use the Parameters list area to add or remove custom Name/Value parameter pairs that are associated with the project and saved in the Workspace. Use the button to add a new parameter Name-Value pairing to the list. These managed project parameters are saved in the Workspace with the new project, and can be edited within the Workspace. By contrast, Project type parameters are saved in the project file (
*.PrjPcb
), and can be edited in Altium Designer. Both parameter types may be used as Special Strings in Altium Designer - access from the Properties panel with a placed Text String selected in the design workspace. Parameters defined for the project can also be viewed on the Parameters and Server Parameters tabs of the Project Options dialog (Project » Project Options).
With the project defined as required, click the button. The new project structure will be created in the specified local and Workspace (server) folders. The project will be opened in the Projects panel, which will show the project and its constituent documents as being Scheduled for addition, denoted by blue cross icons ().
Right-click on the project in the Projects panel and choose the Commit Project command or the Version Control » Commit Whole Project command. You will be presented with the Commit to Version Control dialog. Select the files you wish to commit to the Workspace's Versioned Storage design repository and click the button. Once added, the Projects panel will reflect the fully synchronized state that exists between the files in the remote design repository (in the Workspace) and the local (working copy) repository - as indicated by the associated icons.
In addition, an entry for the project will appear on the Projects page of the Workspace's browser interface.
Commit without Push
For those unfamiliar with Git repositories, or for those just wanting to get their local design changes into the Workspace, using the button in the Commit to Version Control dialog is the cleanest and most streamlined approach.
However you also have the option to Commit to your local Git repository, ahead of pushing changes to the remote Git repository (Versioned Storage) in the Workspace. To do so, select the Commit command as above, and in the Commit to Version Control dialog choose the Commit option from the button drop-down menu. The changes will be saved to the local Git repository for that project, and the state of the files - as reflected in the Projects panel - will become Ahead of server ().
These locally saved changes can be sent to the remote Git repository in the Workspace at a later time by executing a Push command. This can be performed in a couple of ways:
- Right-click on the project entry in the Projects panel and choose the Commit Project command from the context menu, or choose the File » Commit Project command from the main menus. In the Commit to Version Control dialog, click the button. This will just push those files ahead of the server, and commit and push those that are not.
- Right-click on the project entry in the Projects panel (or on a specific file) and choose the Version Control » Push(n) command from the context menu – where n reflects the number of local commits that have been made (ahead of the server).
Once pushed, the Projects panel will reflect the fully synchronized state () that exists between the files in the remote repository (in the Workspace) and the local (working copy) repository.
Make an Existing UnManaged Project Available Online
You can also make an unmanaged project (regular project, or a project currently under version control) available to the Workspace - essentially 'registering' the project with the Workspace and creating a 'mirror' of it. This allows you to enjoy the collaborative features available through the Altium 365 platform, while keeping your original project right where it is. To do this, open the existing unmanaged project as normal in Altium Designer, then right-click on its entry in the Projects panel and select Make Project Available Online from the context menu, giving access to the Make Available Online dialog.
Use the Make Available Online dialog to change the project Name and add a Description. By default, the name will be that of the original project.
Check the Enable Formal Version Control option to add the project under the Workspace's own built-in VCS (Git). This option is unchecked by default, where the project files will simply be stored in the Workspace for basic shared access.
Click the Advanced link to expose the Folder field. This field is used to specify where the folder for the mirrored project - within the Workspace's folder structure - is to be created. The default path for new projects is specified on the Admin - Settings - Projects page of the Workspace's browser interface (by default, this will be Projects\<ProjectName>
). Click the button to browse to and select a different server folder, if required.
With the properties for the mirrored project defined as required in the Make Available Online dialog, click OK. Projects that have been made available online - in the Workspace - will be shown in the Altium Designer Projects panel as follows:
- For a project that is not under external version control and when made available online the Enable Formal Version Control was left unchecked, the project is shown with the icon only. This indicates the project as being registered with the Workspace, that a mirrored project exists, and that the two are synchronized. Saved local files are automatically synchronized with their mirrored project counterparts in the Workspace.
- For a project that is under external version control, the project is shown with the icon to indicate the project as being registered with the Workspace, that a mirrored project exists, and that the two are synchronized. Associated icons reflect the fully synchronized state that exists between the external design repository and the local working copy. Once local file changes are saved and committed to the external design repository, those changes are automatically synchronized with their mirrored project counterparts in the Workspace.
- For a project that is not under external version control and when made available online the Enable Formal Version Control was checked, the project and files will be committed and pushed to the Workspace's Versioned Storage design repository, with the Projects panel reflecting the fully synchronized state that exists between that remote design repository and the local (working copy) repository, as indicated by the associated icons. The project behaves like a true managed project - not just 'registered' in the Workspace, but actually committed and under the Workspace's version control. Changes made to the design must be committed back to the repository in the Workspace.
The mirrored project will subsequently be available from the Projects page of the Workspace's browser interface.
Limitations when using an Existing External Version Control Repository
As mentioned previously, your unmanaged designs may already be tracked under an existing, external version control system (Git, SVN, EPDM, etc...). You can continue using this setup as before, and simply make the designs available to the Workspace by registering them with that Workspace - using the Make Project Available Online feature.
In this mode, every time you make changes to a design and commit those changes to your external VCS repository, that design data will be mirrored to the Workspace in the background, and all needed processing will be performed as usual - preview, where used etc. There are some limitations to be aware of however:
- Creation of a new design project still has to follow the old flow, i.e. create it manually in the external VCS repository, then register to the Workspace (using the Make Project Available Online feature).
- If design changes are made but the commit is not performed through Altium Designer (so externally using other tools), then those changes will not appear for the mirrored project in the Workspace, until the next commit operation is performed through Altium Designer.
- Opening of the project by a second person will require access to that external VCS repository.
- Rights management will have to be setup/maintained in two placess - in Concord Pro and in the master source (the external Git/SVN/etc VCS repository).
Controlling Project Synchronization
Once an unmanaged project has been made available online, controls over its online availability and synchronization are provided through the General tab of the Project Options dialog.
Use the options available in the General region of the tab to make changes to the name of the project and/or its description. These affect the mirrored project within the Workspace only - the name of the local project is not changed.
In the Online Availability and Synchronization region of the tab, the Enable Formal Version Control option reflects the current style of online availability - either simple synchronization (option disabled), or stored under external VCS, or the VCS within the Workspace's Versioned Storage Git design repository (option enabled). Use the option to change between these two as desired. Note that if the local unmanaged project is stored under an external VCS repository, this option will be permanently enabled and cannot be changed.
Should you wish to stop the synchronization between your local project, and the managed incarnation of it that was made available in the Workspace, click the button. The Turn off project synchronization window will appear. Click on the Unlink option, then click OK back in the Project Options dialog. The local project will no longer be associated with the project in the Workspace, reflected in the Projects panel by the local project being presented under the active Project Group (*.DsnWrk), rather than as an entry under the active Workspace. The project in the Workspace remains untouched - it is not removed by this action.
You can always make the unmanaged project available online again. The General tab of the Project Options dialog will present the button, with which to access the Make Available Online dialog. Refer back to the section Make an Existing UnManaged Project Available Online for more information.
Sharing a Managed Project
Once a project is managed (available in the Workspace), you'll want to determine which users can actually access that project. This is done by sharing the project, or rather, by configuring its access permissions. Remember that a managed project - newly created or made available in the Workspace - is shared, by default, with the following:
- The Owner of the project, which is usually the designer who created it (or made it available in the Workspace): with full (Read/Write) access permissions.
- The Administrators role: with full (Read/Write) access permissions.
Access for a project can be configured directly from within Altium Designer by using the Share command. This command can be accessed for the active project, or a focused project:
- Active project - with a source document for the project open as the active document, choose the Project » Share command from the main menus.
- Focused project - access is made from the Projects panel by right-clicking on the entry for the required project and choosing the Share command from the context menu.
The Share dialog will open in which you can configure sharing as required. Use the dialog's Add menu to select the type of sharing you wish to apply - Add User, Add Role, Add Anyone. For a user/role, choose the desired entity in the subsequent Search for dialog.
Opening a Managed Project in Altium Designer
To work on a managed project, you effectively check it out as a local working copy. This is performed directly from within Altium Designer using the File » Open Project command. The Open Project dialog will appear, from where you can choose which managed project to open from your Workspace (when connected to a Workspace, that Workspace will appear in the Locations region of the dialog, distinguished by the icon, and appearing with the name given to the Workspace). Only those managed projects that have been shared with you (you have permission to access) will be listed.
Once opened, the project will appear under an entry for the Workspace, in the Projects panel.
Cloning a Managed Project
When browsing the project through Altium Designer's Explorer panel - configured in its default Project View rather than Classic View - the project can be cloned by clicking the button, at the top-right of the panel. Use the Clone Project dialog to determine the project Name, Description, the Location (to the working copy) and the Server Folder path (within the Workspace).