Management of Projects in Altium Designer

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

Setting up the Create Project dialog to create a new managed project from within Altium Designer. Note that the Advanced options will be appropriate by default.

1. 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.
2. 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.
3. 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 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.

Commit and push the newly created project to the Versioned Storage design repository in the Workspace.

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

Example of committing a new project to the local Git repository.

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.

Make an existing unmanaged project available to the Workspace, essentially 'registering' it with the Workspace and creating a 'mirror' of it.

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 access and to enable sharing with others for viewing and commenting only - a less formal Simple Sync as it were. It is recommended to enable formal version control, as by doing so you will have access to the maximum functionality offered through, and by, the Workspace and the Altium 365 platform.

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 using the Simple Sync methodology. 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 using the Simple Sync methodology. 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.

Simple Sync States

Where an unmanaged project is made available online to the Workspace using the Simple Sync approach (not using the Workspace's formal version control), the current state of the synchronization between local and server-side projects is presented in the Projects panel through a range of icons. These icons, and their meaning, are as follows:

	Synchronized	The local project and the mirrored project in the Workspace are synchronized.
	Sync-in-progress	Changes made to the local project are being synchronized to the mirrored project in the Workspace. For a local project not under external VCS, this occurs when saving a local file. For a local project under external VCS, this occurs when saving and committing local file changes to the external design repository.
	Project is Read-only	The project has been shared with you, but you have Read-only access to it. Under the Simple Sync methodology, the design project can be edited by a single person only (the owner of that project - the one who made it available online to the Workspace).
	Not Synchronized	Changes have been made locally, but these have not been synchronized yet with the mirrored project in the Workspace. This can happen, for example, when the same project is open for editing by the owner/author on two computers (PC1 and PC2). On PC1, the Workspace is subsequently disconnected. On PC2, connection to the Workspace remains and changes are made. On saving the local file(s) the project remains unsynchronized. If you attempt to close the project on PC2, the Closing unsynchronized projects dialog will appear alerting you to this fact. If you choose to close the project, changes will not be available on PC1. To remedy the situation, disconnect from and then reconnect to, the Workspace on PC2. The project will be synchronized with the Workspace. The synchronized data will be reflected on PC1 once the Workspace is connected there too.
	Conflict	There is a conflict between the data for the local project and the data for the mirrored project in the Workspace. This can happen, for example, when the same project is opened for editing by the owner/author on two computers (PC1 and PC2). On PC1, the project is opened and the Workspace subsequently disconnected. Changes are then made and local files saved. Later, on PC2, the same project is opened and, while still connected to the Workspace, changes are made and saved. Later still, connection is made to the Workspace back on PC1. A conflict exists because there are changes locally on PC1, but the Workspace contains the updated data from changes made and synced on PC2.   To remedy the situation, on PC1 right-click on the project and choose the Resolve Conflicts command. The Resolve Conflicts dialog will appear. You have the option to Use Server files (the data from the mirrored project in the Workspace will be used and local modifications will be lost), or Use Local files (the data from the local project will be used and synced to overwrite the current data for the mirrored project in the Workspace).

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 previous flow, that is, it is manually created in the external VCS system. The project is then registered and mirrored to the Workspace using the Make Project Available Online feature.
• If design changes are made but the commit/push is performed by external tools rather than through Altium Designer, then those changes will not appear for the mirrored project in the Workspace. This is corrected when the project is next reopened in Altium Designer, which automatically synchronizes the local project with the mirrored Workspace version. If the changes were made by another user, then the reopened project file(s) will show as Out Of Date and can be corrected using the version control Update command.
• 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 places - in the Workspace and in the master source (the external Git/SVN/etc VCS repository).
• Some features delivered through the Altium 365 platform work only by having a project under the Workspace's native version control system. By keeping your project under an external version control system such features, as they become available to the platform, will not be available to you. You can move from using your external VCS to the Workspace's native VCS - see the next section for the procedure to achieve this.

Moving from External VCS to Workspace Native VCS

In some cases, functionality delivered through the Altium 365 platform - or more specifically an Altium 365 Workspace - can only be experienced by having your project fully managed and stored under the Workspace's native VCS (within its Versioned Storage Git repository). What you can do is create a snapshot of your project, disconnecting it from external VCS and from the Workspace (if already made available there), and then make it available to the Workspace again, but under the Workspace's VCS - starting afresh as it were. To do so, follow the procedure below:

1. Disconnect (remove) your project from the external version control system. This can be performed from your external interface tool to your current VCS, or through Altium Designer. In the case of the latter, while there are commands to remove the project from version control in both the Projects panel and the Storage Manager panel, the cleanest way is to use the Project Packager. Using the Project Packager will create a snapshot of your project, without the baggage of version control and, if you have previously made the project available to the Workspace, it will strip the links to the project in the Workspace.

2. Unpack your 'cleaned' project from the Zip archive created by the Project Packager.
3. Open the project in Altium Designer - notice that it is neither managed (if it was previously) nor under version control. It is therefore a clean, unmanaged project.
4. This next step is only if you had previously made the project available to the Workspace. The packaging process unlinked the project, but the mirrored project in the Workspace still remains untouched. You should delete the server-side project first. Access the Workspace's browser interface (through the Altium 365 Platform Interface). From the Projects page, click to select the project to be deleted, then click the  control and choose the Remove command from the context menu. The Delete Project window will appear - click on the Delete Project and Linked Items entry.

5. Now make the project available online again to the Workspace. To do this, 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. Make sure you enable the Enable Formal Version Control option, as this is what adds the project under the Workspace's own built-in VCS (Git). For more information, refer back to the section Make an Existing UnManaged Project Available Online.

Working with GitHub

Using the GitHub platform as an external version control system (VCS) is a popular way to host and share design projects, and is easily integrated with an Altium Workspace through Altium Designer. As described above, the existing external VCS arrangement is synchronized with an Altium Workspace which allows you to benefit from its advanced data management and collaboration features.

How you normally work with GitHub itself will vary depending on company practices or simply the Git tools you have at hand. In general however, a design project is created in a local Git repository and then Pushed to a GitHub (remote) repository, or an existing project is Cloned to a local repository from GitHub. Once in the local Git repository, the project can be opened in Altium Designer and mirrored to an Altium Workspace (Make Project Available Online), as outlined above.

GitHub Protocols

While there is a range of data transfer protocols offered by the Git VCS, Altium Designer currently supports the HTTP/HTTPS protocol only for connections between a local Git repository and its remote master repository. In practice, the applied protocol is set by the URL prefix specified for the remote repository connection – https://<remote repository>, ssh://<remote repository>, git://<remote repository>, and so on.

GitHub supports both the SSH and HTTPS protocols, and recommends using HTTPS URLs for connections.

► See Which remote URL should I use? on GitHub for more information.

If your external VCS system is bound to a protocol other than HTTPS, such as a GitHub SSH connection, this will be preset in a repository that has been cloned from the remote. As this protocol is incompatible with Altium Designer, an error will be thrown when attempting to integrate the project with an Altium Workspace. If you are unsure of the remote URL protocol that is used for a local Git repository, this can be checked using the git remote - v command.

Use the Git Bash command line interface to check a repository's remote URL setting.

The repository can be reconfigured for a different URL, such as the HTTPS protocol to enable compatibility with Altium Designer, by using the git remote set-url <name> <URL> command, where the URL's prefix specifies the protocol type.

Changing the remote repository connection URL protocol and then confirming with the remote command.

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.

Options and controls relating to having made the project available online are presented on 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:

• Option Enabled - the project (and its source files) are stored under the Workspace's own native VCS (Git). This is the recommended approach, as by doing so you will have access to the maximum functionality offered through, and by, the Workspace and the Altium 365 platform.
• Option Disabled - the project files are stored in the Workspace for basic access and to enable sharing with others for viewing and commenting only - a less formal Simple Sync as it were.

Use the option to change between these two as desired.

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.

This is reflected in the Projects panel after saving the local project, by the project being presented under the active Project Group (*.DsnWrk), rather than as an entry under the active Workspace. A save is required since the links to the project in the Workspace are removed from the project file.

The project in the Workspace remains untouched - it is not removed by this action.

You can sever the connection between your local project and the incarnation of it made available in the Workspace.

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.

A local, unmanaged project can also be made available online - in the Workspace - from the General tab of the Project Options dialog.

Sharing a Managed Project

Related page: Sharing a Design from within Altium Designer

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.

Controls for sharing a design from within Altium Designer can be found in the Share dialog - accessed by clicking the  button at the top-right of the main application window.

Accessing the Share dialog - command central for sharing a design from within Altium Designer.

The following levels of sharing are supported from within Altium Designer:

• Sharing of an actual design - the live (or WIP) design itself, which can be shared:
  • With other members of your Workspace team - for editing and/or viewing. Sharing at this level requires both registration with AltiumLive and active subscription for your Altium Designer licensing. You also need to be connected to your Altium 365 Workspace. An invited team member can viewing the design through Altium Designer, or through the Altium 365 Platform Interface. Editing is performed only through Altium Designer.
  • With people outside of your Workspace team - for viewing and commenting only, through email invite. Sharing at this level requires both registration with AltiumLive and active subscription for your Altium Designer licensing. You also need to be connected to your Altium 365 Workspace. This allows invited stakeholders to view a live, work-in-progress design project from any web browser, anywhere in the world, without gaining access to your full server of design data. As the relevant members of your Workspace team make changes to the design and commit them, those changes can be viewed 'live' by those external people. And this functionality is delivered through the platform, but outside of your Altium 365 Workspace, so all that's needed is registration with AltiumLive to gain access.
• Sharing of a design 'snapshot' - a static snapshot of the design at a particular point in time and shared:
  • By link - available to anyone through a Web browser. Sharing at this level requires neither active subscription for your Altium Designer licensing, nor registration with AltiumLive. A recipient of the shared link uses Altium 365 Viewer to view (but not comment) on the design. Viewing requires no registration with AltiumLive and the link is available for 48 hours.
  • With specific people - available to specified people through email invite. Sharing at this level requires registration with AltiumLive, but does not require active subscription for your Altium Designer licensing. A recipient accesses the design snapshot through the Altium 365 Platform Interface from their email invitation. Viewing requires registration with AltiumLive, but the snapshot is available permanently. Commenting of the design is also available.

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.

Choose which managed project to open, from within Altium Designer, from those currently shared with you.

You have the option to open the project to the default checkout path, or use the  drop-down menu to specify a custom path. The default checkout path is defined as a property of the design repository in which the project resides. For a Git repository (e.g. the Versioned Storage repository that is native to the Workspace), this is the Local Path field found in the Git Repository dialog. For an SVN repository, this is the Default Checkout Path field found in the SVN Design Repository dialog. Access the properties dialog by selecting the entry for the repository - on the Data Management - Design Repositories page of the Preferences dialog - and clicking the  button.

When browsing the project through Altium Designer's Explorer panel - configured in its default Project View rather than Classic View - click the  button, at the top-right of the panel, to open the project in Altium Designer (adding it to the Projects panel).

Cloning a Managed Project

To clone a managed project from within Altium Designer, right-click on the entry for the project in the Projects panel and choose the Clone command from the context menu. Use the Clone Project dialog to determine the Project Name, Description (which is not pre-populated), the Folder path (within the Workspace), and the Local Storage path (to the working copy).

Clone a managed project from within Altium Designer.

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.