Overview

Many factors go into deciding on a revision control solution, and organizations differ in their need for a unique revision and release process.

Team size and structure

Smaller teams can be more agile and experience less risk of having conflicting changes. Larger teams, however, are going to have a harder time coordinating work and are more likely to create conflicting changes. 

Large teams might have each member focusing on a specific part of the design or a fraction of the total assemblies. Small teams, however, might have every member aware of every design file in the entire company. They might have every engineer responsible for the entire lifecycle, including design, validation, fabrication, and verification. A large team might have a matrix org, with separate engineers who specialize in only one of these categories.

A single engineer responsible for creating source files and contract manufacturer files will navigate revision control differently than a team that hands schematics off to a board layout team. That team will then hand files off to a planning and purchasing team. Some organizations have resorted to hefty process documents and procedures in order to ensure the right product is designed and produced.

This isn’t limited to circuit boards. Many organizations require cross-department cooperation with other engineers. Mechanical engineers need to review interference with the enclosure housing or design assemblies to ensure the product can be assembled quickly, reliably, and inexpensively. Firmware and cloud developers need input into the design that may be overlooked or unknown by an electrical engineer.

Project complexity

Every organization is different and has a different workflow and set of needs. Electronics that can be designed on a single schematic sheet with only a single microcontroller are going to be handled differently than a PCBA with multiple FPGAs or microprocessors. Systems that are self-contained require less validation than systems that interconnect with many other peripherals, sensors, or other assemblies. The more complex a system is, the more dependable a revision control system needs to be.

Assembly lifecycle and SKU count

Organizations with fewer electronics assemblies (and are a few revisions old), have a much easier time managing their designs. It is often more difficult for businesses with a fleet of electronics in the field with dozens of revisions, all with different form, fit, and function.

Legacy revision control – file systems

In the past, revision control consisted of keeping separate files with revision numbers and dates tacked onto the filename to differentiate versions. It was relatively easy to open up an old revision, make changes, and no one would know that the changes were there or if they were correct. It was up to the engineer to manage R1 vs R2 vs R23. Also, it was easy for a network version of the files to be downloaded to a local machine and have different designers make independent changes without knowing what the other team members were doing. When generating files for contract manufacturers, zip files might be updated many times to create changes for the CM, with no clear view onto which set of files were “correct.”

Product lifecycle management (PLM) systems

Major improvements came when PLM systems were created. Users could attach specific versions of files to a software system so that everyone could point to the exact files for a revision. It became much easier to share files with the confidence that any given file was the correct version. One of the downsides to this approach is the need for monolithic reviews before the files could be released. Unless users were attaching incremental changes to their PLM systems, PCBAs needed to have everything that changed reviewed at once. This leaves designs open for adding bugs as well as not implementing all of the new features intended for a new design. Design reviews were often multi-week events with spreadsheets to track comments with no real link to individual issues, along with whether or not they got resolved. At some point, all the reviewers had to take the plunge to the next revision and push any missed changes to the next phase.

A large downside to using only a PLM system is that although the deliverables and key revisions of files are indexed, the source files are not tracked. It is up to custom and manual communication as to who is the keeper of the files between releases. If a user’s local machine fails, the files and changes are gone. If the files are kept in a network folder, it can be easy to overwrite changes made by others.

Revision control using Git

With the adoption of Git, users are able to gain the benefits of tracking releases, such as in a PLM, with the flexibility of a local file system that is also synchronized with a network copy. Users are able to perform iterative, atomic, and asynchronous changes to the source files. Much of this can be done offline and then pulled and pushed when a group of changes needs to be harmonized.

Atomic commits speed review

Although nothing is stopping users from creating one single commit after months of progress, the Git way is to create atomic commits that corral changes to a specific section of the circuit. It may seem like atomic commits generate more work, requiring more time to create and review each commit, but they can save time in the long run. By only reviewing small changes, it is much easier to determine if a design has accurately changed and is bug free. The reviewer’s focus is on a small set of feature changes instead of jumping around among all the changes.

By adding well-formatted commit messages, the creator documents the intention of all of the changes, rather than a fraction of highlights.

Atomic commits speed revision

When users check in small changes, they are immediately available for a review. Designers can get same-day feedback on their changes and start making corrections from that feedback. Rather than adding layers of design sediment on top of one another, things that are recommended to change can be changed long before they accrue design momentum and affect adjacent subcircuits.

This helps with things like users selecting new components when similar ICs have already been used in the organization. Component reuse affects volume purchasing and leverages existing design validation.

One designer might select a component with I2C communication without realizing that a majority of the team’s solutions have been using SPI, allowing the design to compound the gains of previous hardware projects.

Atomic commits allow you to revise designs while they are still fresh in your mind. If you get feedback that your DC to DC supply isn’t meeting the power requirements, it is easier to change then and there rather than weeks later after dependent circuitry has been laid out.

The advantage of small changes and reviews is dramatically increased with layout. Whereas schematic design is the logical selection of components that float in a virtual representation of the circuit, PCB layout is a literal 2D mapping of the components and traces, and changes to the design must rip up nets and topologies and force the designer to redo work. Test engineers can validate that test points are added and useful long before the design is close to completion, when it can be cost-prohibitive to change the layout design. Design for Manufacturing (DFM) changes can be requested and implemented in-step with the design, rather than late in the project when work must be repeated. High-speed digital circuits can be routed and approved early, and as the rest of the topology is placed and routed, designers can give their feedback on circuits that affect the transmission lines or areas where the EMI can leak out.

Individual, small changes to the design help reduce work and lower overall costs.

Asynchronous reviews reduce meetings

Whether it’s a room full of people in front of a projector, a daily stroll, or video chat to a co-worker’s screen, asynchronous reviews cut down on in-person meetings. It’s hard enough to tie all of our schedules together, but meetings put a penalty on the opportunity cost of our free time. If we’re in a design review meeting, we can’t be anywhere else at that time. We can’t respond to fires, new opportunities, or the changing landscape of marketing features.

When a user commits and pushes their changes in Git, you can react as soon as you see the notification, or when the time is most convenient for your brain-space. Even if everyone who would be in a meeting were conducting their reviews at the same time, the ability to think independently without a single speaker walking everyone through the design review allows developers to concentrate and focus on their expertise.

Different engineers have different specialties. Time spent on the placement of components and vias in a voltage regulator circuit doesn’t mean additional time needs to be spent in a meeting reviewing the high-speed digital circuitry. The mechanical engineer doesn’t have to sit through hours of meetings when they’re ensuring mounting holes are in the correct location. They can check that the keep-out and height restriction zones are correctly defined and run through a design rule checker (DRC).

Total change history

When using Git, you have access to the total change history of a file. You can see who has worked on it, what changes have been made, and when. It’s an important feature for your first revision of hardware, but it’s critical for long-term designs that can be updated several times a year for many years. When a PCB is at revision 25, it is imperative that anyone who is using it can go into a system and determine what the form, fit, and functional changes are between rev 25 and rev 24, as well as between older versions.

Sometimes circuit functionality is changed, but doesn’t manifest as a problem until future revisions when new changes are added. With total change history, users can rewind to the time that the original circuit was modified to get an understanding of what the changes are and how they affect one another.

Sometimes components are replaced due to a supply shortage, but it becomes necessary to revert back to the old designs when the shortage is gone or it’s demonstrated that the replacement isn’t performant.

Because each change is atomic, the commit message should describe what changed and why. If that isn’t enough, each commit is unique to a user, and you can seek them out to ask about the rationale or subtleties of a feature change.

Git issues and milestones simplify requirements tracking

Git issues allows users to create requirements, bug fixes, and feature requests inside the revision control tool itself. Many engineering teams use an external tool like a spreadsheet, requirements document, or kanban to capture and track requirements. While this is decent project management, there is nothing to guarantee anyone is checking to make sure they are implemented at all, much less correctly.

In Git, you can create milestones that are collections of issues and design reviews. You track your desired outcomes in issues and implement the changes in design reviews (aka “pull requests”).

If you close out all of the design reviews in a milestone, but there are still open issues, then you know there is more work to be done. This brings the atomic nature of Git to project management. Instead of having a monolithic spreadsheet, or a disjointed kanban, each issue is its own “file” and can describe specific requirements or changes. Each issue also has a history of allowing people to discuss the issue describing possible implementations or whether the solutions are working on solving the issues. Issues can be re-opened if they are discovered to not solve the original problem.

There is even automatic closing of issues if you refer to their issue number in a Design Review when you merge, using keywords like “fixes #287”, “closes #876”.

While an organization may still opt to use an external tool for project management, the engineers can add issues and milestones into Git and ensure they are implemented and have visibility to when and where the changes occur.

Git branching is more flexible

Git has an extremely flexible branching strategy that is both powerful and gives you enough rope to trip over yourself.

At AllSpice, we recommend a strategy of using two-plus branches. The main branch is for releases and hardware that is ready for manufacturing. These are files that you know are solid and have been reviewed.

A second branch (the development branch) is for collecting the changes that lead up to major hardware revisions. A typical Git flow strategy uses additional branches for new features. Because hardware files are often binary blobs, merging changes from multiple branches can cause problems. Unlike code, where you can slice and dice the text, hardware design files may require manual merging.

If two designers are working on separate schematic files, it is very easy for them to have separate feature branches and merge without conflicts. On the other hand, if two designers are working on the same layout file, there is currently no text-based tool to chop up the changes and integrate them correctly, as both designers intended.

This can be useful if you want to pursue prototypes with experimental features, while engineers keep developing the main hardware. Because each branch is separate, anyone can make changes and put together a proposed solution, without the revision control software gatekeeping file checkout. The downside to this approach is manual merging if the branch proves useful.

Git gives you the flexibility to create as many or as few branches as your team needs.

Git is faster

No matter which way you’re tracking files, you have to copy them to and from a server. Unlike legacy systems like plain old file systems, PLMs, or SVN which copy all of the files, when you push or pull files in Git, you are only copying the changes. This can lead to extreme time savings over the lifecycle of the project. It doesn’t just save you time, it enables smaller changes more often. An engineer doesn’t have to wait for a large file push if they’ve only added a handful of components.

Git has many software solutions

There are dozens of solutions out there that can used in combination or as a standalone to help get your started. AllSpice Hub gives you hardware-specific features like automatic visual diffs of schematics and layout and creating snippets of 2D files for discussion and issue resolution, multiple ECAD file format support, and a lot more. Here are some other Git clients. 

Cloud solutions like GitHub, Bitbucket, Perforce, Beanstalk, Amazon AWS CodeCommit, Phabricator, Microsoft Azure DevOps, SourceForge, GitLab, and Gitea offer a range of tools from fully managed servers to host-your-own server.

Files can be managed by the command line and integrated into scripts, or checked in and out by desktop clients such as TortoiseGit, GitHub Desktop, GitKraken, GitCola, GitForce, VSCode to name a few.

Your most powerful users won’t feel held back by a specific tool and your newer users can use a desktop client and handwave away Git’s deep feature base.

Git is complex

Because of the vast array of features in Git, it earns the reputation for having a bigger learning curve than other solutions. It’s relatively easy to get started and work on a small project with a small team and never encounter any of the complex merging issues that can crop up.

Unless all users maintain a relatively rigid self-enforced process, they might eventually encounter changes coming in the wrong order, merge conflicts, and an inability to effectively add changes until problems are resolved.

There are many effective solutions for these problems, like discarding local file modifications, resetting the head to undo local commits, reverting pushed commits, and bisecting and marking commits to find when the problem commit was merged. These solutions require a more sophisticated experience with Git and can be disruptive to schedules while the problem is sorted out. Very often, however, once a mistake is made and identified, users can be educated on how to avoid the mistake without needing a complicated solution.

Merge conflicts

It is often mentioned in the hardware design process that it is difficult to merge two different developers’ changes to a single hardware file. This is a problem with all revision control approaches and stems from the way ECAD tools store the data in files. All components, traces, nets, attributes and other file features are interwoven in a file, with no way to discern changes created by separate users on separate local file systems. This isn’t a downside of Git, this is a downside of the ECAD file formats.

Although this problem won’t be fixed in the near future, the software industry has demonstrated significant productivity and reliability boosts by leveraging the ease of merging in text files. It is merely a matter of time before difficult merge problems are resolved and the same file can be worked on by multiple people simultaneously.

Vanilla Git doesn’t show schematic and layout differences

Because Git was developed for software, the tool shows the difference between files in a text format. If you are using vanilla Git, you will have to either pull the changes under review and open them in their native ECAD program or generate review PDFs. Both approaches have their drawbacks.

The pulling solution limits review to only people who have the ECAD license. Those tools are expensive and are usually limited to the handful of engineers who are working on the changes. This often precludes mechanical engineers or planners from effectively reviewing changes.

Generating PDFs either delegates the A/B comparison to the reviewer or requires an engineer to compile a list of before/after slides in a review presentation. This is not only time-consuming, it often leads to incomplete reviews, reviewer fatigue, or misunderstandings of changes.

AllSpice Hub solves this problem by automatically generating visual diffs of the schematics and layout files. The native ECAD formats are processed and generate files that everyone can read: SVGs. The files are hosted and anyone visiting the Design Review will see redline deletions, yellow changes, and green additions. BOM differences are easy to see and are ready to be sent to or reviewed by a manufacturer.

In this image, you can see that all the yellow components and nets changed values or positions. The green components are new.

Git is revision history, not PLM

It is wholly possible to use Git without a PLM system. Users can grant contract manufacturers access to specific repos or releases. Many users, however, will still use both tools in tandem by leveraging Git for the exceptional version control, and PLM systems with their integration into ERP systems and release file access.

Summary

There are many different revision control solutions for your hardware project. The drawbacks of using a plain old file system should be clear. Using PLM systems by themselves is a good step in the right direction, but are updated too infrequently. Centralized solutions such as SVN contain many benefits, but lack the flexibility and speed of Git. 

While we recommend AllSpice Hub for your next hardware project, Git is a great platform to manage your changes and take a little bit of the hard out of hardware.