The Managed Project and Releasing the Design

In a nutshell, Project Management is focused on securely storing and tracking changes throughout the design process, and ultimately, channeling the resulting design through to the creation of a physical item – such as an assembled PCB to be used in the final product.  To meet these needs, Altium Designer provides a range of project management approaches that offer increasing levels of sophistication and capabilities, yet simplify the process from a designer's perspective.

Altium Designer's integration with Version Control systems (VCS) provides the primary mechanism for robust management of design data, while its tightly managed generation of Output files forms the basis for sophisticated design data release mechanisms. In their most advanced form, both the management of design data and generation of output data are centered on the capabilities of the Altium Vault.

The VCS-based project and design document management options that are available can be summarized as follows, ordered by increasing capabilities:

1. External VCS, managed outside Altium Designer
   An installed Version Control System (VCS) such as SVN or CVS that is managed independently of Altium Designer by a client application such as the Tortoise interface. A designer must leave the editing environment to perform VCS operations with a separate, client application.
   – See Version Control and Design Repositories for more information.
2. External VCS, managed within Altium Designer
   An installed VCS such as SVN or CVS managed and accessed through the Altium Designer Storage Manager panel. A designer must setup and connect to the VCS service, but can then perform VCS operations from within Altium Designer, which directly interfaces with the VCS application.
   – See Version Control and Design Repositories for more information.
3. Internal VCS (SVN), managed in Altium Designer
   The SVN application that is built in to Altium Designer is accessed and managed through the Storage Manager panel. Altium Designer works directly with its internal SVN application, minimizing the need for user intervention and setup.
   – See Version Control and Design Repositories and Using Version Control for more information.
4. Altium Vault VCS managing a vault-based or external repository
   The Altium Vault and its own VCS service (SVN) is managed through the Vault's browser interface, and accessed from Altium Designer's Storage Manager panel. VCS repositories created in the Vault can be configured for specific user access (Sharing), and are automatically connected to by Altium Designer. The service may also link to external VCS repositories.
   – See Local Version Control Service for more information.
5. Altium Vault VCS repository hosting advanced Managed Projects
   The Altium Vault and its SVN service host Managed Projects, which offer simplified VCS operations and inherent design collaboration capabilities. Projects are managed through the Vault's browser interface and can be accessed directly from Altium Designer, based on a user's Vault login credentials.
   – See the Managed Projects overview, below.

Beyond the selected method used for project and document management, a board design will eventually be 'released' from the design domain to the manufacturing domains for fabrication, testing and assembly.

At its fundamental level, this involves generating a set of output files that correctly provide the information required to manufacture and populate the board design. At its most advanced level, a preconfigured and fully verified set of generated output files (including a snapshot of the design files) are Released to the Altium Vault as a packaged 'item' revision, which is itself under lifecycle-managed version control. See Releasing a Design, below.

Managed Projects

In conjunction with the Altium Vault, Altium Designer offers the ability to work with an advanced project construct in the form of a Managed Project. Stored within a Vault-based repository, a Managed Project harnesses the Vault's version control and design collaboration capabilities to provide a refined approach to centralized design for small or large design teams.

Thanks to the intelligence built in to the Vault service, tasks such as VCS operations are simplified and automated, and additional design collaboration features such as user access control (sharing), commenting and notifications are integrated with Altium Designer. The end result is a robust and secure project storage format and location that can become the central point for collaborative project design.

The preliminary steps for managing and working with Managed Projects are:

1. In the Altium Vault's browser interface, create a VCS repository in the Vault – see Repository Creation. The Altium Vault installation provides a default SVN repository (DefaultRepository), and new repositories may be added in ADMIN » VCS page of the Vault browser interface.
2. In Altium Designer, sign out then back in to the Vault to automatically connect to the new Vault-based repository – see VCS Repositories.
   The conventional method of connecting to a VCS repository (through the Data Management – Design Repositories page of the Preferences dialog) is not required for Vault-based repositories – the connection is automatically established when you sign in to the Vault from Altium Designer (DXP » Sign in to Vault).

A Managed Project can then be created through the Vault interface or in Altium Designer, or an existing project may be converted to a Managed Project.

Create a Managed Project

A new Managed Project is created in Altium Designer via the standard New Project dialog (File » New » Project), where the Managed Project option is selected and the target Vault/Folder nominated. As with other new VCS projects, the files will be added to version control and must then be Committed to the VCS repository – use the Commit Whole Project or Save Managed Project commands in the Projects panel.

Alternatively, a Managed Project can be directly created through the Projects page in the Vault browser interface. Use the button to open the Add Project dialog, where the Managed Project's name, description, and target repository/folder is nominated. This automatically adds and commits the project structure in the Vaults VCS repository, which can be subsequently opened and added to in Altium Designer.

Convert to a Managed Project

A Vault-based Managed Project can also be created by converting an existing Altium Designer project to a Managed Project. To do so, right click on the project file and select the Convert to Managed Project command.

In this case the opened project is Added then Committed to a nominated Vault repository, while the local version is retained as the working copy. The newly created Managed Project can then be shared with other Vault Users (or user Role groups) to enable a collaborative design environment for that project.

Share a Managed Project

A Vault based Managed Projects can be individually shared with nominated users by setting its access permissions (including read/write restrictions) in the Vault browser interface. Use the Share button () to access the Manage permissions for project dialog, where Vault Users and group Roles can be granted access to the selected project. Vault Users and user Roles are defined in the Users page of the browser interface.

Open a Managed Project

A Vault-based Managed Project can be opened from within Altium Designer (File » Open Managed Project), or from the Projects page of the Vault browser interface (access the Project's page with the button, and select the button). In both cases the Managed Project files are checked out from the Vault repository to a local working folder and opened in Altium Designer.

Releasing a Design

Also in conjunction with the Altium Vault, Altium Designer provides an advanced approach to organizing, tracking and storing the design output files required for manufacturing a PCB design project. This employs an automated process that ‘releases’ a specific package of design output files to the Altium Vault as a read-only ‘Item’ revision, which corresponds to a physical item that may be built. The Vault Item revision created by this PCB Design Release process is stored in the Vault’s version controlled repository, is lifecycle managed, and represents a manufacturable snapshot of the PCB design at the time the Release was created.

Design Releases that follow, as the design progresses, are each committed as a new revision of the Item, allowing a sequence of released revisions to be created as the design changes and evolves. Previous revisions are read-only, and may be viewed or extracted from the Vault at any time.

A board design that is released or 'committed' to a Vault Item (as a lifecycle-managed Revision) includes:

• A Design snaphot: A time-stamped copy of the core project design files (Schematic, PCB, project file etc).
• Released documents: The output files generated by Output Jobs that have been included with the release (fabrication and assembly files, validation checks, printouts, BOMs etc).

The prerequisites for releasing a PCB design to the Vault are:

• An Altium Vault is installed and accessible – the target repository for the release.
• The Altium Designer PCB project includes suitable Output Jobs – design data output generators (for outputs such as print, file or PDF).
• The PCB project includes PCB project Configurations – mapped links between the design source data and a targeted release revision in the Vault.
• The PCB Release process is setup with all required elements in place – the project source data is valid and up to date, a target Vault Item Revision is available, etc.

The essentials of these requirements are outlined below.

Output Jobs and Files

The fundamental method of generating design output in Altium Designer is through a range of available design Output Generators that produced the data files and artwork needed to create the real world version of the design – in other words, the Schematic and PCB Prints, Gerber and NC Drill fabrication files, Bill of Materials (BOM), Pick and Place Assembly files etc that are required to fabricate and assemble the PCB design.

The selected Output Generators and the specific Output files they will create for a design are collectively defined using Altium Designer’s Output Job Editor, which saves the generator to output mapping configurations to an Output Job File (*.OutJob) – created via File » New » Output Job File.

Within the editor, the available Output types are arranged in functional sections (Documentation Outputs, Fabrication Outputs, etc) and are enabled by selecting a sub-type and the design document source. The selected Output is then linked to a target Output Container (such as a PDF, file, or a printer) – as shown above and below.

The Output Job Editor allows a wide range of design output generators to be targeted at output containers (files, printers, location paths etc), and the configuration saved as a OutJob project file.

As the core mechanism for collectively generating manufacturing and assembly files for a board design, Altium Designer Output Jobs offer the following additional capabilities:

• Any number of OutJobs can be added to a given design, so that configurations will be available for specific tasks such as generating outputs for fabrication, assembly, archiving, procurement and documentation.
• OutJob files are in fact portable and can be applied to any design project where a standardized set of design outputs are required. Choose 'PCB Document' as the document source option, rather than a specific design file, to create a generic (and therefore portable) portable Output Job.
• OutJobs can include files for design Validation checks, such as electrical (ERC), Rule (DRC) and Footprint to source comparisons. As such, Validation OutJobs are a specialized 'active' case where the design is checked and the actual output (such as a PDF document) represents the results of the validation process. 
• OutJobs cater for variations in an assembled board design, where different sets of output files are required to manufacture alternative versions the design – such as standard or uprated versions of the product that uses additional components or different types. See Design Variants for more information on board design variations

When releasing a design to the Altium Vault through the Design Release process, any Output Jobs that are included in the design project may be added to the release setup. The Release process in turn is defined by a PCB Project Configuration, which maps specific set of project production data (such as just the bare board or complete assembly variations) and nominated OutJob files to a target Item in the Altium Vault.

PCB Project Configurations

A PCB Project Configuration, in a nutshell, defines a specific collection of design project data for building a particular physical Item in the real world. While this data collection is sourced from a single PCB design project, a Configuration can define a range of different design data collections, such as those required to manufacture a bare (unpopulated) board, an assembled (populated) board or a variation of an assembled board (some components of a different type, or not fitted). Configurations are used by the Design Release process to map the appropriate project source data (including files generated by nominated Output Jobs) to a targeted Item Revision in the Vault.

The defined 'release' Configurations are stored as part of the design project, and are created in the Configuration Manager dialog – Project » Configuration Manager (available when a project document is open).  Each Configuration definition can include design Variant information and Output Jobs, and is targeted at a nominated Altium Vault and an Item within that Vault. The Item is analogous to, and will contain the data for, a physical Item that can be built.

Create Configuration overview

Multiple project Configurations can be created in the Configuration Manager and are subsequently available in the PCB design Project Release view, where the selected Configuration will control the process of releasing the design to the Altium Vault.

The Configuration Manager dialog for a project where four Configuartions have been created, each set up for a specific type of design release.

In the Configuration Manager, create a new release Configuration by nominating the design source options – a configuration name, the desired Output Jobs and a design Variation, if required – and the release target. The right hand panel section represents the target, which must be set to a new 'planned' Item revision in a targeted Altium Vault (see the Target Vault option at the top of the dialog – you need to be signed in to an Altium Vault).

Configurations are arranged to show the source PCB design data in the left hand panel, and its target Vault Item Revision in the right hand panel. 

To create a target Vault Item or select an existing one, open the Choose Item from Altium Vault dialog from the Target Item browser button . Select an existing (or create a new) Vault Folder, then in the dialog's Item Revision area, select Create Item from its right-click context menu. Choose a preconfigured Item type that suits the new release Configuration (design, blank or assembly).

The following Create Item dialog includes the properties for the new Item, most of which are preconfigured to suit the selected Item Type – complete the Comment and Description fields to provide useful information about the Item and its revision. Click OK to add the new Item Revision, which will be in a Planned state (until populated with released design data).

Create or select the Item and its Revision for the current release Configuration.

The newly created Planned Revision is added to the current Configuration when the Choose Item from Altium Vault dialog is closed. The Target Item in the Configuration Manager indicates the newly selected Item, while the Target Planned Revision for Next Release field shows the new Planned revision of the Item that will be the target for the Configuration release – use the field menu drop down selector to choose an alternative Planned revision, if available.

PCB Project Release View

With a PCB project’s required Output Jobs and release Configurations created, the design is ready to be released as a manufacturable set of design data to an Item Revision in the Altium Vault. Each Configuration definition is able to ‘drive’ the release process to generate a specific collection of board design data that represents a particular physical item (such as a fully assembled PCB).

To access and setup the Design Release process, open the PCB Release View from Altium Designer’s main menu (DXP » Design Releases or View » PCB Release View) or click the button on an editor’s toolbar.

The PCB Release View is arranged with selectable tabs, where each tab corresponds to an available release Configuration, and the release flow is graphically represented as a path from the Design Source to the Target Vault.  

The multistage release flow includes sequential processing steps to:

1. Checkout Snapshot – A current copy of all design files in the design project are stored in the target Item revision.  If the project is under version control in a Design Repository (such as a local or network-based repository, or the Altium Vault), a record of the current version control revision and its repository address is also committed with the release.
2. Validate Design – If included in the Configuration’s nominated Output Jobs, all Validation output generators (such as ERC/DRC checks) are run.
3. Generate Outputs – All other defined outputs in the assigned Output Job file(s) are run and committed to the target revision, in addition to the SystemBOM. These will generate the specific data that determine what particular Item can be manufactured from this release.
4. Commit Release – The action of committing the generated outputs and validated design documents (the snapshot) into a new revision of the Vault target Item.

Pre-release checks

The PCB Project Release view operates in two sequential modes – the initial Design Mode, and a Release Mode that is enabled when all release conditions are satisfied. Design Mode is a preliminary setup mode, which also allows the Validation and Generate Outputs processes to be run independently of the release process to check their validity. These processes are defined in the Output Jobs nominated by the current Configuration, and will be run again during the final release process.

To run all outputs associated with the Validation or Generate stage, simply click its associated button in the view's release flow area to trigger the process. The view's lower region lists all output files, and displays their details and current status.

If all outputs have been generated successfully (validations show as Passed and other outputs show as Up To Date), then they will also run without error in the final Release Mode flow – more detailed results are shown in the Messages panel.

Setting up the flow

The design release process is fully enabled when both the design source data and target Vault Item revision are authenticated – that is, the design documents are saved (and committed to version control, if applicable) and a target revision (in a Planned state) is available.

The state of the release flow is managed through the regions in the view’s main Process Flow graphic, which provides release status information and interactive control over the source data and release target.

In terms of left to right release flow for the currently selected Configuration, the region functions are:

• Design Source region: Provides status information for the currently selected design project. Its main Configuration heading is a link to the Configuration Manager.

If the project is in version control, the region text will show its current VCS status and include hints when action is required. If the project has been locally updated for example, a '..has local changes' status is shown in red (hyperlinked) text, indication that it is out of sync with version control and must to be committed to the VCS repository before continuing. Green text indicates that the project files are ready for the release process.

• Target Vault region: Provides status information for the Item Revision and Vault targeted by the selected Configuration. Its main Item Revision heading is a link to the Vault Item view.

The status here will be 'green and ready' if the design release targets are correct and valid in the selected Configuration. Conversely, if for example the Configuration is not correctly mapped/targeted to a Vault Item Revision (which must be in 'Planned', ready for content, state) then the Target Vault region text will be a red '...not mapped to target item' hyperlink – select the link to open the Configuration Manager dialog and establish a target Item Revision.

When all design release conditions are satisfied, the Release Mode will be enabled in the Process Flow's central Mode region.

Design Release mode

Selecting the now available Release Mode option allows the automated release process to be initiated. Doing so will trigger the sequence of design release steps, under the command of the currently selected Configuration – any error encountered will terminate the process.

Initiate the release by clicking the Commit Release button, which will cause each stage in the flow (Snapshot, Validate, Generate and Commit) to run in sequence. The design Snapshot and Generated data are stored in a temporary folder, and if no errors have been encountered, the files are then committed to the target Item Revision in the Vault – the location of the temporary folder is defined in the Data Management – Vaults page of the Preferences dialog.

A successful design release is followed by the Release Summary dialog which includes details of all files released to the Vault, grouped as Design Snapshot and Released Documents collections.

The main Release View, in turn, will indicate a successful release through the 'green' status of all release stages and the listed output files. Note that in the view's current configuration tab, the Lifecycle state the targeted Item Revision will have changed fom Planned to New From Design (or Released, depending on the Item's assigned lifecycle definition).

To view detailed information for the released Item Revision or manage its Lifecycle state, open the Vault Item view by selecting the revision heading text link in the PCB Release view.