We’ve been asked the question, “How can I best manage large complex projects with multiple PCBAs?” Here’s an overview.
PCBA background
One of the most essential features of revision control and Product Lifecycle Management (PLM) is to ensure that the right product is being built using the right dependencies, even when those dependencies are being actively developed.
Most designs are assemblies and require multiple PCBAs, cable harnesses, and assembly instructions. Complex designs are created with multiple levels of sub-assemblies.
You can create repos for each of the components and bring them all together into a separate upper-level repo. Each of the sub-repos can be developed independently and then integrated when they are ready.
You’re able to create Git submodules for the sub-repos.
Types of files that can be used in a submodule
Product Lifecycle Management (PLM) systems typically include anything that changes the form, fit, function, cost, or production yields/speed. Keeping all the information in one assembly repo cuts down on production and assembly errors. It helps with knowledge transfer so all the stakeholders genuinely understand what is being built and how. Here’s a breakdown:
- PCBA projects
- Schematics
- Test Procedures
- Manufacturing information
- Gerbers
- Drill files
- Part Position Files (xy)
- Fabrication specifications
- Bills of Material (BOM)
- Cost of Goods Sold (COGS)
- Assembly Instructions
- Test Firmware
- Production Firmware
- Test Software
- Cable Harnesses
- Enclosures
- Test Station
- Datasheets
Before we dive into how to use submodules, let’s consider the different strategies and their pros and cons.
What is a monorepo in hardware?
Just like in software, a monorepo in hardware is a repository where multiple projects are stored. It is possible to use a monorepo with separate files or subfolders for each sub-assembly and to create commits into the one repo whether sub-assembly A or sub-assembly B are modified.
This approach is best used for smaller, simpler projects developed and maintained by a few people at most. Revision control works best when each subproject is modified independently so that each commit only affects a single subproject. Modifying more than one project per commit is a large vector for bugs, especially if changes need to be reverted or are part of a complex merge.
Monorepos are definitely not recommended if one of the sub-projects is used in multiple higher-level assemblies. Unrelated assemblies will get commits when they don’t change form, fit, or function. It becomes especially challenging when one upper-level assembly requires one revision of PCBAs, and a different assembly requires a newer revision. Keeping these all in one repo invites extra work and mismatched files.
What are subtrees in hardware?
Git Subtrees actually come in two flavors, the Git subtree merge strategy and the Git-subtree command. They both refer to a strategy similar to monorepos where the separate projects are kept in subdirectories.
Unlike a monorepo, with a subtree, you can commit, branch, and merge alongside your project any way you want. You can even extract all of your version history at any time and create a new repo using any specific version.
The Git subtree merge strategy, on the other hand, cannot extract the version history.
Some of the downsides of subtrees are similar to monorepos in that it is up to the user to commit the files atomic to their subprojects. It is very easy to blend commits between a project and its subdirectory dependencies which makes for messy version control. If there is a related change to the two sets of files, it is recommended to make two separate commits for the same revision control action so that the changes can be separated.
Since there are no metadata files like .Gitmodule, users might not even be aware that the subfolders are subtrees that require their own set of processes and disciplines.
Many software developers prefer subtrees over submodules. However, the submodule process is the most accurate analog to traditional hardware PLM strategies.
How do you use submodules in electrical engineering?
Submodules have the benefit of being tied to a specific revision of files that won’t change no matter how much development is happening in the repo. Prototypes and production PCBA revisions can be consistently manufactured with the peace of mind of knowing you have the right files.
Subrepos have a slight downside as they are more complicated than operating a monorepo, but with tools like TortoiseGit, you don’t have to learn the command line interface (CLI).
Another quirk with submodules is that it’s easy to clone or pull a submodule without initializing or updating the directories and be left with empty folders. This can be a benefit if your project is large and only the needed files are downloaded.
Keep reading the step-by-step guide
Want to learn more about how to manage large projects with multiple PCBAs? Read our extensive, step-by-step, knowledge-base tutorial here. It includes more in-depth best practices, along with screenshots of how they can be put into practice within AllSpice’s platform.
