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.
• Viewing Project History - browsing a progressive timeline of major events relating to the project - its creation, commits, releases, clones and MCAD exchanges - with various actions supported where applicable.

Creating a 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 (local project, or a project currently under external 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. The <Empty> entry will create a shell project with no initial source documents.
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 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 tab 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 Save to Server 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 Save to Server 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 Save to Server command from the context menu, or choose the File » Save to Server 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 external 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 Delete command from the context menu.

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 option available in the General region of the tab to make changes to the project description. This affects the mirrored project within the Workspace only.

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 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 in the following ways:

• For the active project - by clicking the  button at the top-right of the main application window, or by choosing the Project » Share command from the main menus.
• For the focused project in the Projects panel - by right-clicking on the entry for the project and then choosing the Share command from the context menu.

If there is no active project - i.e. no project document currently open - then the  button will act on the currently focused project in the Projects panel.

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:

• Share Project - share the actual WIP design itself with other members of your team and/or external contractors outside of the team, as required. Use the available control to determine access rights (Can View by default). View and comment from within Altium Designer, or the Altium 365 Platform Interface. Editing can only be performed through Altium Designer.

• Snapshot on the Web - a static snapshot of the design at a particular point in time that can be shared with others, perhaps for an adhoc design review, or maybe with the manufacturer for a cost estimate. Two levels of sharing are supported:
  • By link - available to anyone through a Web browser. Using the Share dialog to share 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. Using the Share dialog to share 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 an email invitation. Viewing requires registration with AltiumLive, but the snapshot is available permanently. Commenting of the design is also available.

Opening a Project

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. What hapens next depends on whether you are a member of the Workspace team, or have been shared a project outside of the Workspace team:

• Workspace Team Member - the Open Project dialog will appear, from where you can choose which managed project to open from your connected 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 your connected Workspace, 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).

• Invited Stakeholder Outside of the Workspace Team - the Open Project dialog will appear, from where you can access any managed project that has been shared with you from the Shared With Me location.

Once opened, the project will appear under the entry Shared with me, in the Projects panel. What you can do with the project depends on the access rights you have been given to it. If editing rights were assigned to you, you will be able to edit the design normally, which would typically be the case for an external contractor. If you have viewing rights only, you will be able to comment on the WIP design.

Choose which managed project to open, from within Altium Designer, from those currently shared with you as an external stakeholder. Note that access is made to such projects without having access to the Workspace.

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 taken from the Document Path field on the System - Default Locations page of the Preferences dialog.

Cloning a 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.

Project History

Not being able to easily access an historical view of a projects' development journey is quite often a pet peeve for designers and product managers. Too often, a designer has to get to grips with external VCS management tools which can require a fair level of expertise to drive them - quite time consuming when wanting to perform basic project management tasks. Even if you are competent with external VCS tools, they only ever deal with certain aspects of the project - VCS-related actions like opening, cloning and reverting. But what about the wider scope of project management, including releases and MCAD exchanges? Also let's not forget to factor in that most of this would typically require being shackled to the desktop.

Providing an elegant solution to the desire to see such information and interact with it from a single location, Altium Designer, in conjunction with your Altium 365 Workspace facilitates the notion of Project History. A dedicated History view provides a progressive timeline of major events relating to the project - its creation, commits, releases, clones and MCAD exchanges - with various actions supported where applicable.

Facilitating the Functionality

The Project History functionality is delivered through a purpose-made extension - the Project History extension.

The Project History extension.

This feature is only made available, provided the Project History extension is installed as part of your Altium Designer installation. This extension is installed by default when installing the software, but in case of inadvertent uninstall can be found back on the Purchased tab of the Extensions & Updates page (click on the current user control (e.g. ) at the top-right of the main application window, then choose Extensions and Updates from the associated menu).

Accessing the Project History

To access the History view for a project from within Altium Designer, right-click on its entry in the Projects panel and choose the History command from the context menu. The History view presents as a distinct tabbed document (<ProjectName>.PrjPcb History).

Access the history for a project from within Altium Designer.

For a project in your Workspace that already existed prior to the arrival of the Project History feature, its history will initially not be complete. Reindexing of the event data for that project will be performed automatically when the History view is first accessed for that project. Notification will appear at the bottom of the view once the reindexing has completed - click the  control to update the timeline with the full historical event data.

History Timeline - Overview

The History view presents a timeline of basic events that have occurred during the project's evolution. It can essentially be broken down into three key sections, as shown in the following image and detailed thereafter.

Identifying the three key components of the History view.

1. Main trunk of the timeline. Direction of event chronology is from the bottom up. The first event - the creation of the project - will appear at the bottom of the timeline. Subsequent events appear above, with the latest (the most current event) appearing at the top of the timeline.
2. Events. Each time a supported event (see below) happens in association with the project, that event is added to the timeline as a dedicated tile. Each type of event will have a different colored tile and will either be linked directly to the main trunk of the timeline, or have some additional icon next to it (as is the case for MCAD Exchange events).
3. Search. Click the  control at the top-right of the view to access a search field that facilitates basic searching of the project history. As you type your search string, filtering will be applied to the timeline to present only the events relevant to that search. For more information, see Filtered Searching.

Supported Events

The timeline shows a progression of events that happen during the life of a project. Each of these events appears along the timeline as a dedicated 'event tile'. The following expandable sections take a look at the range of events currently supported and presentable as part of a project's historical timeline.

Project Creation

Refer to: Creating a Project, Making an Existing Project Available Online, Cloning a Project

When a project is created, the Project Created event tile will be added to the timeline. This event marks the beginning of the historical timeline for the project. As such, it can always be found as the entry at the bottom of the timeline. The tile for this event can appear in two distinct variations:

• When the project is newly created within the Workspace. The creator of the project is presented by name (and picture), along with the date and time of the project's creation. The description for the project is also displayed within the tile, if one was entered at the time of creation.

• When the project is a clone of an existing project. The person who created the cloned project is presented by name (and picture), along with the date and time of the project's creation. The description for the project is also displayed within the tile, if one was entered at the time of cloning. A link is provided to the original project - clicking this will access the detailed management page for that project through the Workspace's browser interface.

The Project Created event tile is physically connected to the main trunk of the timeline with a solid blue connection line and node: .

Project Commit

This type of event is only supported for a project that is fully managed and stored under the Workspace's native VCS (within its Versioned Storage Git repository). For an unmanaged project that has been made available to the Workspace but is not under formal version control - thereby using the Simple Sync methodology - you will not see any VCS-related commit events on the history timeline. To get this information, you can switch the style of online availability by enabling the Enable Formal Version Control option, on the General tab of the Project Options dialog. This brings the project under the Workspace's native VCS.

For a project that has been made available to the Workspace but is already under external version control, you will also not see any VCS-related commit events on the history timeline. Use your external version control client to examine the project's version control history. Alternatively, you can effectively switch to Workspace's native VCS. What you can do is create a snapshot of your project - performed most efficiently and cleanly using Altium Designer's Project Packager. This disconnects it from external VCS and from the Workspace (if already made available there), after which you can then make it available to the Workspace again, but under the Workspace's VCS - starting afresh as it were. For detailed information on how to do this, see Moving from External VCS to Workspace Native VCS.

Each time you perform a Commit & Push of the project to the Workspace (where the project is managed under the Workspace's internal Versioned Storage Git repository), a Project Committed event tile will be added to the timeline. The person who performed the commit and push is presented by name (and picture), along with the date and time. If a comment was added at the time of the commit and push - through the Commit to Version Control dialog - then that will also be displayed within the tile.

If the project was a local, unmanaged project that was subsequently made available online, then the description that was entered in the Make Available Online dialog will be used in both the Project Created event tile and the initial Project Committed event tile, since the commit and push of the project is performed as part of making the project available online - provided of course that the option to Enable Formal Version Control was enabled.

Example initial Project Committed event tile.

The tile also supports and presents design diffing information, showing more detailed information on what has changed between the current and previous commits. Elements supported include files, components, nets, variants, and PCB structure. The diffing section of the tile summarizes the various elements affected by the commit event, grouped by the following states:

 - element added.

 - element removed.

 - element modified.

Clicking on the tile will expand this diffing section to present the affected elements by name.

Use the available Show More and Show Less controls to interrogate the full listing for each element type. Click on the tile again to return to the summary display.

Click the  control at the tile's top-right corner to access a menu with the following commands:

• Open Snapshot - use this command to download and then open that specific revision of the project (in the Projects panel). The project name will include the date and time at which that revision of the project was committed. Note that this revision is Read-only; you can view, but not edit it in any way.

You can open (for viewing only) any specific revision of the project - directly from the corresponding Project Committed event tile for that revision.

• Revert to - use this command to revert to using the data from that specific revision of the project. The data from the project source documents in that specific revision overwrites the data in your local working copy of the project. Effectively, the project is momentarily closed and then reopened with that reverted data. Should you then wish to complete the reversion, and make that data the Head Revision, you will need to commit and push the project back to the Workspace.

You can revert to any specific revision of the project - directly from the corresponding Project Committed event tile for that revision.

After reverting to a specific revision, and before committing, you can get your local working copy back to the latest revision again by using the Revert to command associated with the latest Project Committed event tile on the timeline.

A Project Committed event tile is physically connected to the main trunk of the timeline with a solid blue connection line and node: . The latest revision of the project (i.e. the last commit) is distinguished by having a white fill for its node: .

Project Cloning

Refer to: Cloning a Project

Each time you clone the project - either through the Workspace's browser interface, or from within Altium Designer - a Project Cloned event tile will be added to the timeline. The person who performed the clone is presented by name (and picture), along with the date and time. If a description was added at the time of cloning - through the Clone Project window (browser-based) or Clone Project dialog (Altium Designer) - then that will also be displayed within the tile. A link is provided to the cloned project - clicking this will access the detailed management page for that project through the Workspace's browser interface.

Example Project Cloned event tile.

The main Clone commands available from within Altium Designer (right-click on the entry for the project in the Projects panel, or click the  button, at the top-right of the Explorer panel when browsing the project), or from the Projects page of the Workspace's browser interface, act on the latest (or Head) revision of the project. When accessing the History view for the project through the Workspace's browser interface, you also have the ability to clone a specific revision of that project. To do so, locate the Project Committed event tile for the required revision of the project, then click the  control at the tile's top-right corner. From the subsequent menu, choose the Clone command.

The Project Cloned event tile is physically connected to the main trunk of the timeline with a dotted green connection line and unfilled node: .

MCAD Exchanges

Related page: More about ECAD-MCAD CoDesign

When working between the electronic and mechanical design domains, the Workspace acts as the bridge between the two - facilitating direct ECAD-MCAD codesign. Whenever changes are made to the project's PCB design and those changes are pushed to the Workspace through the relevant CoDesigner panel, an MCAD Changes Suggested event tile will be added to the timeline. The person who performed the push is presented by name (and picture), along with the date and time. If a message was posted at the time of pushing - through the MCAD CoDesigner panel (Altium Designer), or Altium CoDesigner panel (in the supported MCAD software) - then that will also be displayed within the tile.

Only Push events are currently supported.

Example MCAD Changes Suggested event tile.

When the MCAD engineer makes changes to the PCB in their supported MCAD software and pushes them back to the Workspace, the corresponding push event will be available on the project's history timeline only after pulling the changes from the Workspace into Altium Designer.

Example showing two MCAD-related events. On the left of the timeline's trunk, the push event from the ECAD side, while on the right, the push event from the MCAD side.

The MCAD Changes Suggested event tile is not physically connected to the main trunk of the timeline. Instead, a directional arrow symbol is used, which points towards the trunk: .

Filtered Search

Click the  control at the top-right of the view to access a search field with which to quickly find events of interest along the timeline. The search facility supports basic searching of the project history, with dynamic filtering applied as you type your search string - leaving only the events relevant to that search displayed on the page. The matching text within an event tile is highlighted.

Example search of a project's history. The timeline is dynamically filtered as you type your (case insensitive) search term, with matching entries highlighted within each relevant event tile.

The search facility works with the following information:

• Event tile title.
• Person's name who performed the event.
• Descriptive text (the text sourced from a comment/note/description when the relevant event occurred).
• Diffing data text - in a Project Committed event tile.
• Data set name - in a Project Released event tile.
• Project name - in a Project Cloned event tile and Project Created event tile (when created through cloning).

To clear the current filtering and return to the full timeline, clear the search field - either by selecting the current text and pressing the Backspace key, or by clicking the  control at the far right of the field. Alternatively, click on either the Clear Filter control in the box summarizing how many events are being shown (at the top of the view).

Updating with New Events

Whenever a supported event happens in relation to the project, that event will be detected and made available to the History view automatically. Notification will appear at the bottom of the view shortly after the event takes place - click the  control to update the timeline with the new event.

A manual refresh is also provided, performed by clicking the  control at the top-right of the view.

Project and Design File Renaming

You can directly change the name of a PCB project (*.PrjPcb) or any of its constituent design files (*.PcbDoc, *.SchDoc, etc) by using the Rename command - available from the right-click context menu for a project in the Projects panel.

Examples of renaming a project and one of its design files, locally from within Altium Designer. Those changes will be synchronized with the Workspace when you save and send the changes to that Workspace.

With renaming performed, save the changes to the Workspace using the Save to Server command (available from the same context menu for the project). File rename synchronization is maintained between the local working copy of the project and its linked/mirrored counterpart in the Workspace. Additionally, when the project file name has been renamed and the project saved to the server, the Workspace automatically changes the managed project's Name parameter to match.

Conversely, when the name of a managed project is updated through the Workspace's browser interface, the change is propagated to Altium Designer when the project is next opened.

To edit the properties of an existing managed project in the Workspace, select its entry on the Projects page, click the  control above the listing of projects, and choose the Edit entry on the associated menu. Change the name for the project in the subsequent Edit Project window that appears.

When the updated project is opened (File » Open Project), an initial dialog provides the option to align the project file name with the new project Name, force the project Name to match the existing project file name, or allow the two names to be different.

Options available if you have renamed the project on the Workspace side.

Working Copy to Server Project Sync Resolution

The application of fully managed, version-controlled PCB projects relies on the tight synchronization between the project's local working folder contents and the Workspace's versioned storage. If this relationship is disrupted by changes made outside of the normal processes, the managed project structure can become corrupted.

Possible changes that break the local-remote storage synchronization include manual actions such as renaming, moving, or copying/cloning a working project folder. These issues are detected and addressed through a choice dialog that highlights a recommended action based on the situation. In general, its options are to make the folder project a new managed project, to resynchronize the folder project as the current managed project, to remove the project's relationship with the server (make the project unmanaged), or to ignore the current disparity.

Options to get you back into sync if you have manually changed the location of your local working copy of a project.

Other more complex synchronization disruptions may be caused by changes in the server identity, such as when the server itself has been renamed or moved, when a local project file has been overwritten with one that contains different server identity parameters, or the project's target repository has changed. Such issues create a disparity between the server and the local project repositories, and are reported by warning dialogs or dialogs that provide a resolution choice.

Options to get you back on track if the repository targeted by the local working copy of your design project has changed.

Soft Delete

Flexible functionality is available for removing managed design items such as Projects, Components and Released data directly from within Altium Designer, from the Explorer panel. Operating as a 'soft delete', the removal process provides increased options and information as you proceed, including relevant links to source items for review purposes. In the Workspace, deleted items are moved to a dedicated Trash location, where they can be retrieved (Restore) or completely removed (Permanently Delete) from the Trash page of the Workspace's browser interface.

Soft delete in action. Here, a project is being deleted, along with its related release (if manufacturing packages had been created from any releases, those would also be deleted).

Where a managed item has been soft deleted, this will be flagged in relevant areas of Altium Designer, wherever that item was being used or referenced. For example, for a soft deleted component item, this is indicated during project Validation and also in component access locations such as the Properties panel and the project's ActiveBOM document.

Example of a soft deleted component being flagged as such elsewhere in the software.