Git For HW Guide 2.0

The
Git for
hardware
guide
www.allspice.io
Table of Contents
4 Why use Git: pros & cons
14 Revision control concepts
22 Commit best practices
31 Pushing & branching
43 Design review basics
54 Generated files best practices
60 Assemblies best practices
65 Issues & milestones
72 Git platforms
www.allspice.io
Why use Git:
pros & cons
Chapter 1: Why use Git for hardware?

Chapter 1: Why use Git: pros & Cons
Why Use git for hardware?
Overview
Many factors go into deciding on a revision control solution. Each organization is different and has a need for a
unique revision and release process.
Team size and structure

Smaller teams can be more agile and have less risk of having conflicting changes. Larger teams are going to have a
harder time coordinating work and are more likely to create conflicting changes. Small teams might have every
member aware of every design file in the entire company, whereas larger teams might have each member focusing
on a specific part of the design or a fraction of the total assemblies. A small team 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 who then hands 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.
Every organization is different and has a different workflow and set of needs.
www.allspice.io
Project complexity
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 less than a handful of electronics assemblies that are only a few revisions old have a much easier
time managing their designs than 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
The original revision control was engineers 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. It
was also very 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 with PLM systems. 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
need 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 tended to be multi-week events
with spreadsheets to track comments, with no real link to individual issues and whether or not they get 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.
www.allspice.io
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 focuses 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 the highlights.
Atomic commits speed revision

When users check in small changes, they are immediately available for a review. Designers can get feedback on their
changes on the same day and start making corrections if anyone has feedback. Rather than adding layers of design
sediment on top of one another, recommended changes can be implemented 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
www.allspice.io
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 or 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, and the people who need to spend their time reviewing the
placement of components and vias in a voltage regulator circuit don’t need to spend their time during a
4
www.allspice.io
meeting reviewing the high-speed digital circuitry. The mechanical engineer doesn’t have to sit through hours of
meetings when they’re interested in ensuring mounting holes are in the correct location and 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, but 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 simplifies 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
4
www.allspice.io
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 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, but 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
www.allspice.io
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

Although we recommend your next hardware project use AllSpice Hub and our hardware specific features like
automatic visual diffs of schematics and layout and creating snippets of 2D files for discussion and issue resolution,
there are dozens of solutions out there.
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
4
www.allspice.io
resolved.
There are many good 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 the 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.
www.allspice.io
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.
Schematic diff with changed components in yellow and new components in yellow
Git is revision control, 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, in general, to manage
your changes and take a little bit of the hard out of hardware.
www.allspice.io
Revision control
concepts
Chapter 2: Revision control has made huge

strides in the past 15 years. The most
popular and functional tool has been git.
Chapter 2: Revision control concepts
Overview
The hardware engineering discipline has come a long way over the last half-century. Gone are the days of taping out
a PCB design and keeping designs in a physical flat-file cabinet. New solutions throughout the decades required IT
staff to create and manage network locations to store designs. Still, the maintenance and upkeep of the designs
were on the honors system, and each design was only as robust as the weakest member of the team. Even if files had
an ultimate destination, they were often passed around on “sneakernet” with code reaching systems on floppy disks
or thumb drives. Many engineers used informal and ad-hoc release processes where they would zip their files and
tack on revision numbers whenever they forgot something and needed to add it later.
Revision control has made huge strides in the past 15 years. File repos no longer need dedicated IT employees to
set up and maintain servers. Numerous providers offer turnkey solutions for revision control. The most popular and
functional tool has been git.
Because git started as open source, anyone can create interoperable tools. Dozens of companies offer git platforms
for you to keep your file changes. Although there are many different git solutions with their own features added on,
they all have the same fundamental functionality and basic usage set.
Decentralized
One of the biggest changes and advantages of git is that it is decentralized. Previous revision control software and
strategies relied on a single source of truth. Centralization has certain advantages, like everyone having access to
the exact same set of files and the final released files being unambiguous. There are a lot of downsides, though. In
order to make a change to a file, you either use a system with the first change to a file going through, or you need to
use a checkout/check in process. Locking files can prohibit productivity and can often prevent people from
contributing their changes while someone else works on the design. Centralized revision control also limits the
types of changes you make to the design. It can be prohibitive to create an alternate design with prototype or
experimental changes.
4
www.allspice.io
www.allspice.io
Decentralized revision control gives everyone equal footing to look at and make changes to the design. Because
everyone has a copy of the design on their local filesystem, they can make whatever changes they want to the files
and push them to the server when it makes the most sense. Some might think that a centralized design would create
a process that is more rigorous and produces the correct intended design, but with a decentralized approach, every
change must be reviewed before being merged into the design.
Users of a decentralized system push their changes to the server, and the maintainers decide which of the changes
get accepted into the repository.
Decentralization may seem backward to some, but the added flexibility allows for more people to participate more
frequently.
Source files and output files

Modern revision control separates files into source files and output files. Source files are things like source code that
compiles into an executable, which is an output file. Firmware is no different, with source files that get compiled into
an output binary file that gets uploaded to the microcontroller, microprocessor, or FPGA. With hardware designs,
the source files are schematics, PCB layouts, 3D CAD files, and cable wiring harnesses, to name a few.
In a traditional software development git repo, the only files tracked are the human-generated source files. The
output files are not tracked, as the source code changes and are only attached or associated with the project upon
release.
There is a very strong argument in a hardware design process to keep many of these output files in the repo. Some
people think the process is source control and only track the source files. What’s really happening is revision
control, where you track the revision of the files.
4
www.allspice.io
www.allspice.io
It may make a lot of sense to track output files. Bills of Material (BOM) can be checked-in to run planning activities
like generating cost of goods sold (COGS) or finding availability of parts, or even replacements. Gerber files can be
used by a mechanical engineer to determine if there is interference with fasteners, the enclosure, other PCBAs, or
internal wiring. Fabrication packages can be circulated to contract manufacturers to obtain quotes and feedback
into board stack-up, blind/hidden vias, or soldering processes that require parts to be moved. Saving netlists can
allow people to run automated tests or checks against the design that would have to be manually run against a 2D
schematic file.
Checking-in the output files also guarantees that everyone has access to the same outputs. Two different users
might have their ECAD tools setup differently and generate files in a different way, or with different features. There
is also the matter of re-generating output files at a later date. With software, the argument is the files can always be
re-created whenever you need them, but the same engineer generating the same files months apart might include
unintended changes. The best time to capture the output files is the same time they are generated.
A final argument for capturing output files is hardware prototypes differently than software. With software, you can
create tests and run them, but with hardware, you need to physically make the changes to a device. If you are
capturing the changes as you go, you can follow along with what happened to the PCBAs in the lab as prototype
firmware, white wires, and circuits attached with flying leads are added and tested.
Commit, push, branches

With git, your changes to the design and files are captured in commits. Each time you make small and related
changes to the file, you can create a commit with a message of what happened. The changes aren’t available to
anyone besides those who have access to your local filesystem.
Because git is decentralized, the committed changes must be pushed to the repo in order for anyone else to see or
use them. Commits are pushed to branches. If you have a single branch system (which is not advised), all of your
pushed commits will be to the main branch and considered “released”. If you use more than one branch, changes can
be pushed to a development or feature branch and reviewed before being allowed in a main branch.
4
www.allspice.io
www.allspice.io
The use of branches allows the segmentation of work into bugfixes, or the development of specific features.
Different users might have their own branches so they can commit changes without a short-term conflict on files.
Branches also allow users to run experiments or create a proof of concept designs without messing up the main
design files.
We’ll cover best practices for commits, pushing, and branches in later chapters, but for now, all you need to know is
that file changes are pushed to a branch.
Pull requests / design reviews

In git, the changes accumulated in a branch can only be merged into other branches using a pull request (PR). For
example, if you created a branch to eliminate noise from an amplifier circuit and pushed all of your changes to a dev
branch, you would need to create a PR and approve it for the files to get merged into the main branch.
At AllSpice, because we focus on hardware development, we call our PRs Design Reviews. We feel that PR is a
confusing label as what is happening isn’t just a request to pull the changes from the branch, but to review the
changes in a formal process like a hardware design review. Most electrical engineers are very familiar with a design
review process and understand that it is more than an attempt to merge files. Design Reviews are an opportunity to
make sure the intended changes work as designed and have no other side effects.
Design reviews in git allow users to comment, request changes, or block the process. Once a design review is
started on a branch, new commits can keep coming in to fix requested changes until the design review is completed
and the files are merged. After the design review is approved, any new commits to that branch must be merged
using a new design review. Some git processes ask or require that you delete a branch after merging and create a
new branch for future changes. We do not recommend this for a hardware design and will cover more in the chapter
on branching.
You should invite all stakeholders to a design review. In legacy hardware development, design reviews can take
several days of meetings towards the end of the design calendar. By breaking up the changes into smaller chunks
and reviewing them sooner, the reviewers can make sure their change requests have more impact on the project.
Instead of carrying on for weeks with hardware that needs to change, your team members can digest the changes
and make their needs known before it costs a lot of money and time to change.
4
www.allspice.io
www.allspice.io
Planners and purchasers need to be added to design reviews. Hardware designs should generate an accurate BOM
and COGs as soon as possible, even if the design is only fractionally complete. Cost overruns is one of the most
common design problems, and catching expensive components or circuits early will give your team time to meet
cost objectives.
Marketers should also be kept in the loop and on design reviews. One of the other common frictions in hardware
development is marketing requirements not being met. Whether it’s the cost per channel, output current,
measurement fidelity or speed, UX features, radio output, or heat generated, someone should be reviewing the
marketing specifications in addition to the team’s design specifications. It’s much easier to determine that you need
to design a different radio if the marketing department sees that the range on the amplifier isn’t what’s been
decided to be built.
Mechanical engineers are a no-brainer to include on changes, being able to ensure board outline, part fencing, and
keep-outs are met, components aren’t too tall, and heat is properly dissipated.
Experienced engineers on other projects can also be added to reviews. Design reuse is important and an extra set of
eyes might notice that the designer is reinventing the wheel when there is already an equivalent subcircuit on an
older design that can be copied. When new components are added to library, engineers can review them and
recommend other components in order to not pull new part numbers.
Manufacturing engineers can identify things like single or low quantity parts that can cause additional costs to the
design, when a similar part can be re-used. Performing design reviews early and often allow the PCB traces to be
evaluated early and offer views into whether the board will need to grow layers or add expensive and slow
complexities like buried and blind vias.
Test engineers are often invited to contribute very late in the development, but adding them to all the design
reviews allows them to specify test points and the addition of built-in self test (BIST) designs. It’s easier to write test
firmware in lock-step with the design than at the end when everyone must perform manual tests until the test code
is completed. The test engineer can even work independently from the production firmware developer and add a
separate firmware build for use in validation or verification.
4
www.allspice.io
www.allspice.io
Merging
One of the caveats of using git for hardware is that merging files has an added complication. Unlike software,
hardware source files are often binary blobs. Schematics are 2D pictures of circuits that are stored as non-human
readable text. With software, individual functional components would have their own files separate from their
connections, so it is easy to make changes to a specific functionality without affecting the operation of any other
component. The way most ECAD programs structure their designs, it is hard for multiple people to make changes to
a design without stepping on each other.
It is possible to open up some designs in a text editor or script, but it isn’t feasible for more than a fraction of the
design to be done this way. When two different people make edits to the same schematic or layout file, it can be
extremely difficult to reconcile the differences. Very often, if two different subcircuits are on the same file, the
easiest way to merge changes is to take one user’s changes via git, and then manually edit the files in the ECAD
program. The future will give us more adept ECAD tools, but for now, if more than one person edits one file, one of
their changes will have to be copied and pasted using a graphical editor.
We recommend tackling your merging strategy before the work is done. It is much easier for someone to check out
incremental work and make their additions, knowing there is no more work to be done than to have someone
manually copying and pasting changes. It is possible to lock files using git large file system (LFS), but there are many
other ways like project management software or plain old communication to see who should or shouldn’t be
working on a file.
Releases
Releases aren’t part of git proper but are an addition that have been adopted by many tool providers. Tags are a
formal part of git and are used to tag specific commits of code. Releases expand this by adding the ability to add files
to the tagged design.
Although we recommend adding many of your output files to your tracked files that get commit to the project,
releases are an opportunity to mark production or prototype-ready files. It may take several commits to fix up your
design once you think you are finished. It may take a couple of days of small changes to clean up silkscreens, move
reference designators, or update fab files based on your final PCB stack-up or specification. Releases are a special
way of marking the final files that other people will refer to when manufacturing your device.
4
www.allspice.io
www.allspice.io
If you use a separate PLM or ERP system, releases are where to store the files before they get uploaded to your
planning or purchasing system. It’s up to your team whether you want to use the PLM as the final source of truth,
and only have your users pull files from the PLM system. It may also be advantageous to give read-only accounts to
your non-design team in order for them to do their jobs more efficiently.
Summary
Git has created a lot of value for companies, allowing them to finish their designs on a faster schedule, fewer bugs,
and higher yields. There are many complexities to git, and it earns the reputation for having a steep learning curve,
but it is relatively easy to get started. Simply put, git is a decentralized version control system for your source and
output files. You push your committed file changes to a branch in the repository. After you conduct a design review,
the changes are merged from one branch to another. When you are ready, you tag commits to give them a label. If
you are ready to fabricate your design, or want specific files to be sent out, you create a release from a tag and
attach your files.
4
www.allspice.io
www.allspice.io
Commit best
practices
Chapter 3: An overview of the ways to

commit; the good, bad, and the ugly.
Chapter 3: Commit best practices
4
www.allspice.io
www.allspice.io
Overview
Revision control can be overwhelming when first starting out. Engineers used to releasing files once per PCBA
revision can be daunted by commits. It’s very easy to finish working on a section of a schematic and instantly jump to
another and keep the development momentum flowing.
Some engineers take a liking to frequent updates as it can be fun to stay organized. Others might begrudgingly
follow a process but feel it’s too much overhead or that it slows them down. Others might not realize they’re even
working on disparate changes in sequence or when to segment and label their work.
There are no one-size-fits-all solutions in how to manage your changes. There are, however, guidelines that produce
correct hardware with a minimal amount of overhead and can be modified to fit your team’s process and your
personal tastes.
Technical background
As a quick review, users make changes to a file or files and then commit those files to their local repo. When they are
ready, they can push one or more commits to the repo. When they push the files to the repo, they can choose which
branch to push their files. There are more complicated scenarios, but let’s start with the user being the only one
creating changes, with no need to fetch the list of remote changes or pull the changes to their local filesystem.
Commit to the correct branch

There are many ways to break things in git. Parallel development branches can make a lot of sense, but if you start
mixing changes between branches, the two branches become like twisted noodles and changes intended for one
branch get associated with the wrong development line.
There are many ways to fix things in git, and sometimes new bugs are interjected. Without backups, it’s possible to
destroy large chunks of your work, even the entire repository. Git is a powerful toolbox, but this toolbox contains
power tools that can rip through well-organized branches and cause hours of work to fix.
4
www.allspice.io
www.allspice.io
There are worse things than losing work. Lost work can be recreated with known, good rework. It’s expensive and
time-consuming but is a fraction of the cost if misbranched commits make their way into a purchase order. ECAD
tools are visually controlled, not file controlled. You might have to manually repair commits by opening up ECAD
files and copy/pasting. If you do this with schematic components, nets, or tracks on a PCB, you stand a good chance
of introducing a bug, removing a feature, or changing the intended functionality.
The easiest way to avoid one of the biggest causes of problems in git is to commit to the correct branch. We’ll cover
branching more in future chapters, but all of the following advice will be moot if you have to undo and mix/match
changes.
Commit related changes
Committing related changes can mean many different things in a hardware design, depending on the lifecycle.
Hardware, unlike software, is massively parallel, and the design components are not broken down into small
functions that live in small files. The way circuits are interconnected is similar to code, but different from software’s
function prototypes inputs and return outputs.
It would be prohibitive to schedules and sanity if changes were scoped to one commit per component or per net, but
sometimes it might make sense to make a commit for an individual IC, especially if it is a critical part of the design
like a microcontroller, microprocessor, FPGA, or SOIC. It may even make sense to create a commit for an individual
IC if it is complicated, has failed in the past, or just has a lot of pins.
“Label every net on main microcontroller U47”
“Connect all open nets on ADC U17”
Hardware often iterates with loose ends. There are many unfinished commits that are fine in hardware revision
control that would be unthinkable in software revision control. Early stages of hardware design often have lots of
empty blocks, diagramming loosely how the design interoperates. Many of these blocks might remain until much
later in the design. It is not common for software developers to add that much pseudocode or empty code blocks,
but it is very common for electrical engineers to leave non-functional stand-ins.
4
www.allspice.io
www.allspice.io
“Place a block diagram of relay control ckt”

“Add all PMU ICs, unconnected”
Sometimes it’s too much work to document every component going into a design, especially when they’re added in
batches. Other times, a single commit is needed for a single new component.
“Add voltage regulators to library”

“Add ACT1746, Motor Driver, TI, DRV8243-Q1 to library”
It’s possible to affect dozens or hundreds of components in a commit. Sometimes changes are related because they
all affect the same voltage rail. Sometimes it’s because all the serial data lines are changed. Changes aren’t always
limited to a functional subcircuit. Often it makes sense to make a commit if you need to change all of one type of
component.
“Add +3.3V to all powered chips”

“Connect all I2C nets”
“Change all load resistors to 1K”
“Change all capacitors from 0805 to 0603”
After the initial circuit design, changes should become narrower in focus and should highlight small changes like
upgrades or fixes.
“Add isolated optofets to relay drivers”

“Fix current driver bandwidth”
One problem that engineers face is wanting to fix bugs as they see them, bouncing from their task to correct the
error, and then jumping back to their original task. It might be better for the engineer to create an issues.txt file or
add issues to the git repo and add changes they want to make to the file as they go. That way, they can save the
changes they want to make until they can file a separate commit message or group it with a series of related
changes. Because hardware mistakes are expensive, It’s better for the engineer to correct the mistake in-situ rather
than forgetting about it. The best practice, however, is to defer the changes and keep a log of the issues so the
project changelog can be more coherent.
4
www.allspice.io
www.allspice.io
It can be hard to know what changes are related, and every engineer has their own style and mode of thought. It’s
better that everyone strives for the goal of related changes and commits changes rather than waiting for the perfect
moment or grouping. This leads to the next guideline.
Commit often, perfect later

It’s better to get the hardware changes into the system, even if they’re a little bit wrong. It’s okay to copy the first
10k resistor you place and use it as a stand-in for every resistor on a page in order to capture the topology. It’s also
okay to take the time to edit the resistor value each time you copy it, knowing you might have to come back and
select actual components rather than just changing the value of an ideal resistor. If the engineer places generic
components and then replaces them back-to-back, then it’s okay to wait until the circuit is complete to place a
commit. Nothing, however, should stop the engineer from committing a partially wrong circuit and blocking the
partially right subcircuit.
Git is all about change control, not change prevention. It’s important to break the changes down into small enough
chunks and iterate later. Some engineers might leave themselves a note like “Change Resistor values to match
Reference Design.” Other engineers might make an issues file or create an issue with git. Keeping the momentum
going by allowing yourself to commit half-finished work trains you to look for good opportunities to segment the
work. Some wrong change is better than no good change.
A single engineer might create several changes per day, or dozens, depending on how they segregate their work. If
you only have a single commit at the end of the day or week, you run the risk of overwriting the correct parts of a
design and be unable to revert back. It becomes incredibly hard to conceptualize and distinguish all the different
changes. On the other end of the spectrum, making hundreds of commits a day generates too much work to review.
Obviously, there’s no right answer to how often and how few changes to commit, but it’s better to err on the side of
too many, rather than too few. If you’re not sure, have a discussion with your team about commit frequency and
style. Soliciting feedback about your commits from the people you work with creates a healthy team.
Another good rule of thumb to use is to commit whenever you may need to rewind the current state. If you’re about
to tear up a section of a schematic or PCB layout, it might be a good time to commit. If you’re swapping out
components, it’s always good to have a “before” commit so you can roll back your “after”. Save your current file, make
a meaningful commit, and move on to the new task.
4
www.allspice.io
www.allspice.io
Test your design before you commit

There are many ways of testing your hardware design. Some of them come baked into the EDA tool like the (Design
Rule Checker) DRC or error log files for exporting changes between the schematic and PCB.
In PCBA designs, it’s often impossible to fix all the DRC errors until very late in the design. It’s okay to check-in files
with errors as long as the errors are tracked. We recommend adding your log files to the project to track the errors.
Hardware bugs are expensive. If you run your DRC before every commit, you can not only track errors, you can see
when errors are introduced. Making DRC checks as part of your Continuous Integration / Continuous Deployment
(CI/CD) process gives everyone viewing the change an idea of what is fixed, and what remains to be done.
If you are close to the end of the design, or at a stable release, it’s a no-brainer to run the DRC every commit. If your
files pass the DRC, you make changes, and the files pass the DRC again, you have a lot of confidence that the
changes are good. If they fail, you’ve caught a bug in your implementation. It’s best to automate the process, but
even if it’s manual, it’s an extremely high-value, low-effort action that can reduce countless problems.
There are other ways of testing the circuits. Some EDAs allow you to run simulations on circuits using SPICE or
other simulators. This is an interesting tradeoff, because it often requires making a rudimentary twin of the
schematic. It can be expensive to keep the two in lockstep, and the process of modifying the simulation schematic
can introduce bugs and false confidence. Just because the simulations pass, doesn’t mean the actual circuitry
matches the simulation 1:1. A logic simulation might guarantee that the 1s and 0s are happening in the right order
and functionally correct, but might not take into account timing, transmission line errors, noise, or discrepancies in
voltage levels.
Many design teams relegate simulation to a fraction of the design process to create the circuits, but not for
verification after the design is set. It’s expensive and often not as reliable as desired. Simulations will be the future of
CI/CD, but for the moment, the schematic tools aren’t as productive as they could be. Try to simulate when you can,
but don’t be afraid to defer simulations when it takes more time than it saves or when the models aren’t accurate
enough for meaningful tests.
4
www.allspice.io
www.allspice.io
Specialty simulations like high-speed digital interference, EMI radiation, and antenna simulations should be run as
soon as they can be modeled and tracked. These are all reasons PCBAs need revisions and it is easier to fix any
problems right after you’ve created them rather than later in the project when you have to rip up a lot of layouts.
If you have the test and it can be run in a short amount of time, it should be run before making commits. Longer
simulations can be run periodically or before a design review. There is no sense in holding up your design and
commits if the simulation takes several minutes to run.
Write good commit messages
Good commit messages should tell you what changed and why. Stakeholders should be able to read the summary
sentence and understand the scope of what changed and the reasons for the change.
Good commit messages should be short. The general rule of thumb for the subject line to be no more than 50
characters, although some teams extend this to 72 characters, or 8 characters shy of an 80 column string. It may be
frustrating at first to try and fit everything into the subject line, but this coaxes you into better summarizing the
change.
Any additional information can be added below the subject line. For example, maybe you want to refer to all the
part numbers that were added, or the reference designators of resistors that changed. Subtle or difficult to
understand changes should be given a sentence or two. The same is true of bugs or challenges that are being fixed.
Well-structured commit messages help out when it’s time to do a design review and merge all of the changes. If a
commit message is too vague or hard to understand, it might delay and raise questions that can be addressed when
the commit is made.
If you are using a text editor or command line, always add a blank line after the summary, with the longer
explanation happening at line 3. Most git clients will take care of this for you. Adding the blank line between the
summary and full description helps make the entire commit message more readable.
4
www.allspice.io
www.allspice.io
Use the imperative mood

It’s very common for new git users to use the past tense when making commit messages like “Added bias resistors to
transistor network,” but the preferred convention is to use the imperative mood like “Add resistors to transistor
network.” The reason for this is to switch from the mentality that something changed in the past to what changes
will applying this commit do to your design.
The handy rule of thumb is to think of every commit summary by finishing this sentence:
Imperative: If applied, this commit will

Replace OpAmp with Higher Bandwidth ACT1378
Connect DAC to amplifier circuit
Add voltage translator to I2C nets
Fix noise issue on dithering ckt
Bad:
Fixed bug with Y
Changing behavior of X
There’s nothing to say that your organization can’t stick with the past tense, but using the imperative mood will
make it easier to work on a team when you have many different changes to merge from a development branch into a
main or release branch. It makes more sense to apply a fix than to “apply a fixed.” Changing the language of your
commits will help you conceptualize the changes and how they fit into the merge workflow.
If you’re looking for more examples, all the commit examples in this article are written in the imperative mood.
Summary
No matter how you style your commits and messages, the goal is to design good hardware. Good commits that are
made of short and related changes will help the project flow better and make incorporating changes much easier.
Writing good commit messages helps everyone, including yourself, to know exactly what each commit does and why.
When it comes time to merge all of the changes into a release, you can be more confident of commits that follow
these guidelines.
4
www.allspice.io
www.allspice.io
Pushing &
branching
Chapter 4: Taking commit best practices

from chapter three and learning how to
push and branch.
Chapter 4: Pushing & branching
Overview
In the previous chapter, we covered git for hardware commit best practices. To review, changes to the files are
captured in commits to your local filesystem. Commits should collect small, purposeful, and related changes to the
files.
When you’re ready to apply these changes, you push the committed files to a remote repository. The repo might be
your own filesystem, a server sitting in a closet, a hosted git solution like GitHub, or a platform specifically designed
for hardware like AllSpice.io.
Push to the correct branch

As stressed in the previous chapter, always push your commits to the correct branch. When you clone your repo
locally, git should automagically download the project files that associate these files to that repo. The remote server
contains access permissions for pushing your commits to the repo.
Part of always committing to the correct branch means restricting people who don’t know how to correctly commit
to the correct branch. Every user should be trained on git and given some practice projects to work with before
being given write access. It’s easier to prevent a mistake than to correct it. Training should include pair check-ins and
pushes for users who are new to git.
Once you have identified the correct branch, push your files to the branch. The commits aren’t part of the final
design yet. The branch is a collection of commits that have been pushed to the remote repo. The commits get
merged into your main or release branch via a Pull Request (PR). Because AllSpice is hardware focused, we refer to
PRs as Design Reviews (DR). After releasing the Design Review and merging the files from the development branch
into the main branch, the Design Review is closed.
In software development, this is usually when the development branch gets deleted and a new branch gets created
for the new work. Because of the nature of ECAD files, they do not merge easily. If you change one location in a
schematic in one branch and then change another location of the schematic in another commit, you cannot easily
merge the files.
If you keep your development branch, any new commits to the development branch require a new Design Review to
merge the pushed changes. Commits pushed to a branch accumulate and then are merged when a Design Review is
completed. 4
www.allspice.io
Branching Strategy: Main and Develop
Git two-branch strategy, merging from dev branch to main branch
www.allspice.io
Because hardware development differs so much from software development, we recommend a branching strategy
specifically designed for working with ECAD files. It’s not only simpler, it will often be more productive than the
traditional software approach.
Each repo contains two branches, one main and one development (dev) branch. The main branch is the default
branch and contains all the “correct files” and the development branch includes the work-in-progress changes.
When the engineers are ready for their work to be released, you create a pull request or design review from the dev
branch to the main branch. When everyone is finished reviewing the design review, one of the users merges the
collection of commits and makes copies of them on the main branch. The source files are effectively “released” once
they are in main.
We encourage your team to rename the two branches to something familiar or related to your current process.
Prototype→Release, WIP→Final, and Development→Production are all excellent labels for the pair of branches.
This strategy has the advantage of being extremely simple, making onboarding easier and remembering how it
works as simple as counting to two.
This approach is not without its drawbacks. If you keep only one development branch, all the pushed commits will be
included in the next design review. You will have to do some fancy command line work or use a git client to remove
commits or cherry pick some of them to a new branch. The single development branch is more susceptible to errors
over time. There are many command line tools that can destroy or mutate your branches beyond recognition.
Although all the changes that are merged to the main repo will be saved, you may wind up finding your development
branch hopelessly corrupted. You also miss out on the advantage of segmenting the work by user or functional
change.
Even with all these potential issues, we still recommend a dev→main branch pair for new users.
Branches: Keep or Delete

In the software world, most branches are deleted after the design review is completed. The history of commits is
still maintained in the merged branch, so there is no archival reason to keep the branches. Many users find stale
branches to be cumbersome to look through once the list grows beyond a certain size. Other organizations might
have a genuine reason to keep the old branches around. Either way, you can follow a more sophisticated approach
to branching.
4
www.allspice.io
Branching strategy: git flow
Git flow strategy is a process that starts off with the dev→main branch pair, but adds additional feature branches
that merge into development, which in turn merges into main.
Each feature branch can be as specific as fixing a bug, adding a subcircuit, or contain all of the prototype changes for
an entire circuit board.
If the user wants to fix a bug, they would create a bugfix branch and commit and push one to a few commits that
change the files needed to fix the bug. The files edited in the bugfix commits are merged into dev with a design
review. The final design might incorporate changes from more design reviews into the dev branch before
conducting a final design review and merge into the main branch.
4
www.allspice.io
In the beginning of a design when many different components and cross-functionality are being added to the
schematic, it might be too much granularity to keep separate feature branches. Other groups might want to create a
feature branch for large or important sub-circuits like an FPGA. Other teams might want to create separate feature
branches so that different people can work on different schematic pages.
Because of the merge problem with ECAD source files, it is only wise to divide work when the changes can be
limited to one person per file that changes. If two people are making different changes on the same file in separate
branches, the merging process becomes a manual copy/paste that can lead to bugs and incorrectly transcribing the
merge.
Most pcb layout files are a single file and cannot easily be partitioned among users, and should not be included in
parallel branches. Schematic files are often separated by page or sub-module files and can be worked on by more
than one person. If the file changes are going to be on separate files, they can be worked on in separate branches.
It is possible to lock files and prevent commits to them using the Large File System (LFS) lock feature, but that
doesn’t stop people from editing the files and attempting to push their committed changes.
Git flow requires much more coordination between team members. They may wish to set up an external project
management tool to coordinate which files each developer can edit and how the work can be separated into
separate branches.
www.allspice.io
Release branches
www.allspice.io
An optional part of git flow that can be applied to any branching strategy are release branches.
Release branches exist between development and main. They are an insulating layer that allow a collection of
feature branches to be merged with the dev branch and then merged into a main branch. When it’s time to send files
to a contract manufacturer, you will use the release branch to collect all the changes that are ready for fabrication
and merge them into the main branch with a design review.
Release branches are different from a development branch in that there are many release branches, one per
release, but only one dev branch. The release branch is usually forked from the development branch and then
deleted upon merging into main.
The only changes that should be pushed to a release branch are to fix errors, add documentation, fabrication files
and other release tasks. No new features should be added either to the release branch or by merging in changes
from the dev branch.
www.allspice.io
Branch filtering
www.allspice.io
It might be helpful to think of a physical analogy. Consider each branch as a bucket of liquid. Each time you add
changes to the branch, you add a little more liquid. You may think or hope the changes in the branch are correct, but
you can’t know until you hold a design review. Each person on the review acts as a filter, catching impurities in the
water. It’s a lot easier to filter out problems when they are small and related to changes. It’s much easier to review
large collections of changes if you know they’ve been filtered through a feature branch design review. Each layer of
the filter makes it easier to detect issues and integrate the changes. Each layer of the filter, makes it a little easier to
make sure the final product has soaked up the design defects and missed market features.
Some organizations add additional branches like prototype, pilot, and final to their branch hierarchy. Each additional
branch adds a chance to verify and validate all the changes to the system but also adds another stage where the
problems can be discovered and fixed.
It’s possible to maintain a new product introduction (NPI) workflow with only two branches, but the separate
branches make the prototypes and final assemblies easier to distinguish. You can save a lot of money by not
releasing failing, low-yield boards if you use the branch filtering system.
With hardware, it’s often required to build prototypes and small batches and wait weeks to months to make the
next change to the design or the process. This filtering allows the deployed, released files to co-exist confidently
while the files are being edited with fixes as they are discovered.
www.allspice.io
Deviation branches
Unlike the previous branching strategies that all flowed to one final main branch, deviations are offshoots from main
or a release branch that are used to track changes that are applied to a subset of PCBAs after they have been
assembled.
There are a lot of reasons to create deviations, but the fundamental reason among all of them is to save money and
pull in the schedule. If a batch of PCBAs isn’t functioning, it is extremely expensive to scrap the boards and purchase
new hardware. It might not be acceptable to wait for a new batch of boards to be assembled if there is a physical
change to the board that can be corrected.
It doesn’t make sense to make a main release for a change if it is only applied to a few or a few hundred circuit
assemblies.
Most organizations use some form of deviation to modify and track boards so they can be released into the lab or
field, and the users would have a way of knowing that the electronics they’re using are different from the mainline
revision and in what way.
Some deviations bring a failing circuit board to perform identically to the form, fit, and function of the main design.
• Replacing a consumer IC with a more expensive and over-specified, but available part
• Replacing a component with a taller part from the same part-family
• Adding white wires to add similarly performing components with different pinouts
Deviations can also contain small to large variations on the main design's form, fit, or function. Very often, prototype
fixes start off as deviations to the main PCB, with cuts, jumpers, and new circuits added to test out the design
changes. Some customers or field installations might require a change from the original spec that can be captured as
a deviation.
The best method of dealing with deviations in git is to use the main release that the PCB is based on. If you are using
git filtering, then deviate from the prototype, pilot, or production branch.
www.allspice.io
Custom branching structure
Expect the unexpected. No single git workflow is a one-size-fits-all solution. Even if you’re using a two-branch
dev→main structure, it still might be a good idea to create extra branches when the need arises. Git flow can be
modified with extra workflows that are either temporary or part of your everyday process. There are no perfect
answers to how you should structure your project, so feel free to model the branching in a way that makes your
team productive. A large percentage of software projects use git flow, but many more use a custom or hybrid
approach.
Summary
Git branches are powerful and useful. You can get away with two branches, a few, or an ocean of branches that come
and go as your development progresses.
Start with one of these suggested workflows and then use your own experience to design the workflow that best
suits your team. Talk with everyone who contributes, reviews, or consumes the files in the project and come to a
consensus on your own localized best practices.
www.allspice.io
Design review
basics
Chapter 5: How git design reviews, also

known as "pull requests," allow for
asynchronous reviews.
Chapter 5: Design review basics
Overview
Every hardware engineer is familiar with traditional design reviews. In the past, it made a lot of sense to gather a
group of people in a room, stare at a projector screen, and manually walk through the schematics and PCB layout.
Every person has a chance to voice their input and create action items.
The downside to this is that reviews could only happen during time slots when everyone or as many people as
possible are available. It also only allows for one person to comment at a time, and while they are commenting, no
one else can be looking through the design and offer their own review actions. It also follows along with the
narration of the presenter, meaning if someone has a particular specialty or is interested in a specific sub-circuit,
they have to wait until that part of the walkthrough. It also means that if the narrator doesn’t cover something, it can
get missed. Old-style reviews are useful, but they leave a lot of potential bugs and stones unturned.
Git design reviews, also known as a “pull requests”, allow for asynchronous reviews. You can still have a formal
meeting and track changes externally, but before everyone meets, you have a chance to circulate the design. Many
of the design issues can be resolved before stepping foot in a meeting room. Because the review is virtual, you can
invite more people to the meeting. Domain experts like mechanical, manufacturing, and test engineers can be
invited to more reviews and not worry about schedule conflicts. Reviewers also get more time to review and get to
work at their own pace. Instead of many people sharing an hour or two, with a mono focus, each team member can
review the features of the design where they are experts and defer to others’ expertise on sub-circuits where they
are not.
Design review basics
At its core, a design review merges changes from one branch into another brach. Because of the problem with
merging ECAD files, we recommend using a two-branch strategy like main and dev. In this case, a design review
would merge changes from the dev branch into the main branch. You can also read our chapter on branching
strategies for more flexibility.
4
www.allspice.io
www.allspice.io
When you create a design review, anyone with access can continue to commit changes to that branch and the new
changes will be merged when the design review is complete. This is how designs get fixed during the review. If you
want new changes to be added to the repo, but aren’t part of the design review, you must create a separate feature
branch. Keep in mind that creating changes in parallel with your design review means that the new features will
have to be manually updated with the changes from the reviewed branch after the review is complete.
The easiest way to create a design review, is through the web interface. Navigate to your repo, click on the Design
Reviews (Pull Request) tab, and click New Design Review (New Pull Request).
AllSpice design review (PR) tab
After you’ve created the new design review, select the from and to branches, noting that most systems use a right-
to-left direction.
4
www.allspice.io
www.allspice.io
AllSpice merge branch selection
The design review isn’t created yet. The system will show you a list of commits that will be merged. After you have
reviewed the changes, you can click New Design Review to move to the next step.
AllSpice new design review creation process
4
www.allspice.io
www.allspice.io
The design review still isn’t created yet. Fill out the title and description, and optionally add labels, milestones, and
assignees.
AllSpice new design review form
Click on Create Design Review to finally create the review.
AllSpice new design review creation

4
www.allspice.io
www.allspice.io
Labels
Labels are like categories and are re-used throughout the life of your repo. You can add labels to a design review,
issues, or milestones, and the same labels are shared among them.
This is a list of the default issues included in an AllSpice repo.
AllSpice's default labels
4
www.allspice.io
www.allspice.io
You can use more than one issue, and it’s often handy to mix things like level of importance along with the types of
changes inside the review. AllSpice uses labels like bug, dfm, feature, mechanical, and layout to let people know what
type of review is happening.
Labels are customizable, and you can add as many of them as you need to match your existing process.
Milestones
Milestones are collections of issues and help let people know what is being fixed or changed in all of the committed
changes. Note that when you close the design review, the issues on the milestone will not automatically close.
Milestones are usually created before the work is committed, but there is nothing wrong with creating a milestone
at the last minute and adding the issues to help organize your project management.
Closing issues
To close the issues when the design review is complete, add them to the design review description with one of the
following keywords followed by the issue number.
close/closes/closed
fix/fixes/fixed
resolve/resolves/resolved
4
www.allspice.io
www.allspice.io
Dependency to issues
You can add issues that prevent the design review from completing until they are closed by adding them to the
dependency list. Any issues that are open will prevent the design review from merging with an error message. This
is different than adding issues in the design review description as that lets you close issues when you merge the files
in the design review. This is also different from milestones, which do not need to be closed and will not be closed
when the design review is completed.
Assignees
Assignees are different than reviewers, although they sound similars. Assignees are the people who are responsible
for managing the design review and have full rights and access to the review. One person can create the design
review and assign it to another person or group of people who are fully responsible for completing the review. You
can also assign someone and co-manage the review, with all assignees having equal permissions as the creator.
Reviewers
Reviewers are pretty straightforward. They are the people who are responsible for looking at your file changes,
milestones, and design review description and determine if the committed changes are ready for merging or if
additional changes need to be added. All reviewers must be collaborators on the repo. If you find that you can’t add
any reviewers, it might be because there are no collaborators set up.
Reviewers can comment, approve, or request changes. By default, if a reviewer requests changes, there is nothing
stopping an assignee or the creator of the design review from merging the changes anyways. Likewise, the design
review can be merged regardless if any or all of the reviewers approve. It is unwise to ignore the approval or
requested changes of a reviewer. After all, that is the whole point of the review, to solicit the advice of others and
integrate their wisdom and experience into your design. If you are going to merge without approval or after
someone has requested changes, it is best to leave a comment as to why.
4
www.allspice.io
www.allspice.io
Branch protection
To set up your repo to allow reviewers to block a review, go to repo→settings→branches and click Enable Branch
Protection.
Repo branch protection
Select “Block merge on rejected reviews” to prevent the merge from completing when someone requests changes.
Select “Block merge on official review requests” if you have reviewers who have not approved the design review.
Repo merge blocking
If you are an admin to the repo, you can still merge the design review, regardless if there are official review requests.
The merge button will turn red to indicate that only admins can merge the files.
Design review cautioning merging until official reviews are complete
4
www.allspice.io
www.allspice.io
Likewise, if none of your reviewers has requested changes, the design review can be merged by an admin.
Design review merge
Design review checklist
You can add a checklist to your design review that shows the progress of completion of the checklist. Simple add
“- [ ]” to indicate a line item that is not complete. Add “- [x]” to indicate an item that is completed. You may also
manually click on the checkboxes to mark them as completed or uncompleted.
When viewing the design review summary, you can see how many steps of the checklist have been completed. You
can see here that 2/4 of the checklists have been completed.
Design review with 2/4 tasks completed
You can create your own design review checklist from scratch ad-hoc, or you can place a template in
.allspice/pull_request_template.md. If you want a copy of AllSpice’s template, they keep a copy of it here:
https://hub.allspice.io/AllSpiceUser/PCBDesignReviewChecklistTemplate/src/branch/main/.allspice/pull_request_t
emplate.md
4
www.allspice.io
www.allspice.io
Default design review checklist
Summary
Git design reviews (pull requests) offer very powerful tools to help you and your team review your designs. They are
inherently asynchronous, and allow for much more productivity when reviewing changes. It is worthwhile to explore
all of the features and to see how they fit into and augment your current review workflow.
4
www.allspice.io
www.allspice.io
Generated files
best practices
Chapter 6: Source? Version? What's the

difference?
Chapter 6: Generated files best practices
Overview
One of the biggest differences between using git for software vs git for hardware is that software tends to use git as
source control whereas hardware tends to use git as version control.
Source? Version? What’s the difference?
Source control
In a source control repo, you only track changes of original source files. If part of the toolchain generates files like
object code, linked libraries, or executables, the generated files are not tracked.
The idea is that the same source files can always be used to consistently generate the same output files.
www.allspice.io
There are more mundane technical reasons like output files increasing the total file size of the repo. These extra files
have to be pulled and increase the total time to synchronize with the repo. Many generated files aren’t human-
readable, and it doesn’t make sense to include comparisons to different versions of the file, as humans can’t review
them.
The compromise in source control is to create releases from specific tags and attach selected files for release.
Release scripts can be created to override the downside of having to attach files manually.
Version control
In a version control repo, you track additional output files generated by the toolchain, at every commit. You don’t
have to track all of the files at every commit, only the files necessary for your process.
Regulation
Some industries like medical and aerospace have very strict records keeping requirements and some of the output
files from the PCBA process are required to be kept.
COGS and lead time

It’s fiscally responsible to track changes that can affect the bottom line of the PCBA. BOM changes are an early and
frequent indicator of the cost of the product. Not only do components have a price tag, but they also cost money to
place on the PCB. PCBs and fab costs can be approximated using the area of the board, number of cutouts, hole
sizes, number of holes, total component count, number of unique components, and number of through-hole and
surface mount components.
Planning and purchasing are a huge part of electronic design and need access to your files that help them calculate
price and lead time. Even if your BOM is hard to automatically parse, it’s still worthwhile for someone to have access
and then manually produce a cost of goods sold (COGS).
Catching budget or schedule overruns early allows you to waste less time refactoring the board after you’ve sunk a
lot of cost into the design.
www.allspice.io
Fabrication files
Output files like the gerbers and fab files are never too late to track. It’s incredibly easy to have a perfect PCB file,
with all the traces, pads, holes and fills where you want them, and then generate an incorrect gerber file. Layers can
get merged or transposed. Elements that you thought were on the silkscreen layer could be on a documentation
layer. Different layers might have different scale settings. Your tool might be outputting metric traces but the drill
files could be in mills. There are dozens of problems with gerber files that can cause the wrong PCBA to be
fabricated.
It’s also beneficial to check your gerbers early and often. It’s easier to fix silkscreen footprints and reference
designators early before you’ve added too many footprints.
PCB board stack-up can be checked, both to evaluate cost, but also to make sure transmission lines, power
distribution, and emissions are properly designed and routed.
Contract manufacturers (CM) don’t read your PCB files; they read your gerber files and fab files. If you don’t
correctly mark traces for controlled impedance or correctly specify the dielectric layers of the board stack-up, the
manufacturer can’t guarantee your high speed or radio signals are going to transmit correctly.
The fab file contains a wealth of information about the various processes and options of the PCBA. You might have a
perfectly good PCBA, except with the wrong finish or dielectric specified.
The drill files can be used to determine if you can save money by using fewer drill bit sizes.
The x/y position files can be used to see if any of the components are too close or if there is a problem with mixing
smt and through-hole components.
It’s important to use your CMs to your advantage during the design. If you only submit files at the end of the project,
you have only a limited amount of time to integrate suggested changes, or to spot bugs in the files. It’s
recommended to track these files and to submit them to a CM for review several times during the process for quote
and for finding issues. Between formal submissions, having the files tracked means you can audit them and use the
extra time to ensure correctness.
www.allspice.io
Design rules check (DRC)
It’s incredibly important and useful to track your design rules checks (DRC). In the beginning of the design, you have
no DRC errors. As you add components, you’ll start to get more and more errors until the design starts to wrap up
at the end. It’s a lot easier to tell the difference between DRC errors that are a problem and ones you can ignore, if
you track the changes and work on fixable errors when they’re committed. If you run the DRC and there are no new
errors, then the changes you’ve committed have passed an integration test.
One of the most common errors is to accidentally move components and traces a small amount without realizing it.
Sometimes when pushing and routing, a trace is moved outside the view window. It happens to everyone. By
tracking the DRC and checking what fails, you’re able to spot errors as you inject them.
Simulation files
Simulation files don’t necessarily have to be generated or tracked at every commit. It may be important to be able to
prove the functionality at different times during the design. If you don’t save the simulation outputs, it may be
possible to revert to an earlier version of code and miss the differences that cause the environment to generate
different simulation waveforms.
Prototyping files
Often some aspect of the design needs to be physically prototyped to ensure the circuit will work as intended.
Bringup procedures, oscilloscope screenshots, and prototype firmware all should be tracked and captured. It’s not
only a good basis and reference for validation and verification, but it also makes sure you can revisit your prototype
testing if there are problems with the design.
Hiding diffs
If you’re concerned that your design reviews (PRs) have too many diffs that aren’t readable, you can hide the diff by
adding specific filenames and filename patterns to the .gitattributes file and set the linguist-generated flag.
The file will still show up as having changes, but it will be collapsed in the web interface, meaning you can quickly
skip over files that you can’t change.
4
www.allspice.io
www.allspice.io
Summary
There are many reasons to track your generated output files in a repo. It’s not a convention in software repositories,
so it requires putting on a different hat to understand the cost and schedule savings to a project. After your first
design cycle, you can decide if individual files are appropriate to track or not and whether they’ve saved you time,
budget, and energy.
4
www.allspice.io
www.allspice.io
Assemblies
best practices
Chapter 7: Options for when you begin

creating final assemblies and integrations
of various subassemblies.
Chapter 7: Assemblies best practices
Overview
Most electronics designs are more complicated than a single PCBA. Very often, designs are compartmentalized into
multiple interconnected PCBAs, wiring harnesses, enclosures, mechanical fasteners, labels, packaging, and anything
else necessary to run the design.
Creating a repository for each PCBA makes a lot of sense to track each PCBA’s files independently, but what are
your options and best practices when you want to start creating final assemblies and integrations of the various
subassemblies?
External organization
One of the simplest methods of organizing your assemblies is to leave it out of the revision control tool. You can use
something as fancy as a PLM system, or as low-tech as a text file or spreadsheet to keep track of what PCBs are part
of a sub-system and how they interconnect.
The downside of this approach is that none of the interconnections are kept in revision control. Cables can become
quickly outdated, and it’s easy to route the wrong signals between boards. If PCBAs aren’t synced, the pinouts from
one PCB might not match the connections on a linked board. It’s easy to create simple misunderstandings like
flipping the pin rows or confusing which is pin 1 and what direction the pin numbering increments.
It’s also easy for circuit boards to become out of lock step with one another. Changes to one PCB might be
introduced that make it no longer compatible with other PCBs in the upper-level assembly. Sometimes it’s
necessary to fork a PCB with older revisions being produced and used in parallel with new changes.
www.allspice.io
Vanilla folders
The next simplest method of organizing repos is using folders on your local machine. Each folder consists of an
upper-level assembly with the subfolders being subassembly repos. This helps group the correct revision boards
with one another without much extra overhead.
This can solve the problem of using a PCBA from two different releases in two different situations. One upper-level
assembly contains a repo checked out to one version of the release, and another upper-level assembly can contain a
subfolder with the repo checked out to a different release. Both folders can co-exist with changes being added to
the separate branches without affecting the upper-level design.
This method is more complicated when the same version of a repo is used in multiple locations. Each subfolder
would need to be cloned, fetched, and pulled separately. It is very easy to lose sight of which folder is the working
copy when you need to make a change to the repo once and pull the changes to every instance of that folder.
The other main drawback to this method is that the organization is external to any system. It lives on a single
person’s local machine and isn’t viewable on anyone else’s machine without synchronizing. It’s not incredibly reliable
or robust and has no way of ensuring the design hierarchy. It is, however, simple.
Subtrees
Although we don’t recommend git subtrees, we should mention that it’s a slightly more formal version of using
folders. Subtrees allow you to clone a repo in a subfolder of another repo. It doesn’t add any new metadata files. This
means that the subtree files are mixed in with your upper-level repo and it won’t be readily apparent to others.
If you make commits to the subtree repo, they will be stored in the host commits. It is extremely easy to confuse the
two and make commits that span the subtree and the upper-level host folder. It is up to the user to separate the
commits to each subtree. It also requires a commit that is explicit from the subfolder to the subtree repo. Because of
the non-obvious project organization and the chance for cross-committing, we cannot recommend this approach.
www.allspice.io
If you do pursue subtrees, know that there is a difference between subtree merging strategy and the subtrees
command.
Submodules
Submodules have a bad rap as being overly complicated or difficult to learn, but they are the simplest and most
robust tool for managing repos with subrepos that behave as you would expect them to. Creating a submodule will
clone a repo in a subfolder and pin it to a specific commit. It will also maintain the git files so that changes to the repo
can be pushed as well as pulled, although we recommend only using the submodule as a read-only reference.
We recommend creating a repo for each level of an upper-level assembly and then clone submodules into
subfolders to show the subassembly hierarchy. Although it’s possible to use these submodules to make edits and
commits to the subassemblies, we recommend using these repos to keep track of upper-level assemblies and only
pull committed changes as the submodules change and write the changes to another folder elsewhere.
In order to keep the changes to submodules separate, it is recommended to clone a separate working repo in a
different folder from the upper-level assembly. Edits to the submodule are commit and pushed from this working
directory. When the upper-level assembly is ready to accept these new changes, the user pulls the changes from the
submodule in the assembly subfolder.
By separating the working directory and the assembly directory, you allow for users to work simultaneously on the
subassembly independently of the upper-level assembly. You can fix bugs, add features, or repurpose an existing
PCBA design without altering the assembly hierarchy. Likewise, you can specify a hierarchy of PCBAs without
putting a block on changes to any of the subassemblies.
In the following example, we show the folder Assembly5678 in yellow, containing a subfolder submodule of
PCBA1234. The only changes that should be commit are in relation to how the assembly is put together, i.e., all the
subfolders. If you wish to create changes for PCBA1234, we recommend cloning that repo to a separate folder that
is not nested inside the assembly directory.
www.allspice.io
Assembly
subassembly
read only submodule
read / write repo
Assembly Tree
The benefit of using this approach is that you have assemblies that are obvious to everyone. The local filesystem
matches the remote filesystem. Everyone who views the upper-level assembly in the repo will be able to tell which
repos are submodule repos and will point to the exact intended commit. By moving the editable working directory
to an external directory, you separate the changes from the subassembly and the upper-level assembly, gaining
revision control without worrying about changes to the assembly affecting the nested subassembly.
It might be useful to think of the work-in-progress repos as being a library where the files are edited, and the
assembly is where the references to the library are checked out for other applications to use.
If you’re interested in trying out submodules, we have a how-to guide.
Summary
Because most electronic designs contain a hierarchy of components, it is important to be able to specify how the
components fit together while continuing to edit and refine the source files. Whether you use an external system to
keep track of the relationships, nested folders, or nested repos, you have a lot of flexibility to create assemblies in a
way that makes sense to your team.
www.allspice.io
Issues &
milestones
Chapter 8: In hardware project

management, it's critical to capture all that
your team wants to work on and schedule
who works on what and when.
Chapter 8: Issues & milestones
Overview
Hardware project management is one of the most important facets of delivering reliable hardware under budget
and on time. It is critical to be able to capture all of the things your team wants to work on, and schedule who works
on what and when.
Third-party productivity
There are many third-party productivity tools for managing and visualizing technical work, like Microsoft Project or
Atlassian Jira. If your team already has a successful history with a third-party tool, you may want to keep using what
works. It may also be necessary to use a third-party tool to coordinate project elements that aren’t related to
developing electronics. Perhaps you need to keep track of packaging material design, shipping logistics, or help
organize your marketing team.
You may also decide to use multiple project management tools, using third-party tools for work that is done outside
the electronics and native project management for the PCBA design.
It is also possible to disable the native issue tracking and set up your projects to point to third-party tools. The
native project management tools are tightly coupled to the git workflow and offer powerful features.
Issues
Issues are the atomic building block of productivity. They could be features that are specified in a design resource
document, bugs that crop up during the design, sub-circuit design notes, or components that need to be replaced
after going to end-of-life.
AllSpice repo issues page
4
www.allspice.io
www.allspice.io
Issues contain a title that is the objective of the issue. When the objective is complete, the issue is closed. Issues also
contain relationships to other project management tools like labels, milestones, projects, and assignees. You can
subscribe/unsubscribe to an issue, set a due-date, or add dependencies to other issues.
AllSpice issue history
Anyone can comment on an issue and leave advice and requirements or close/reopen the issue.
The issue timeline is a history that keeps track of all the changes to the relationships as well as comments and
conversations from other users
Issues should be relatively small in scope and limited to a sub-circuit,

schematic sheet, or component. If the task can be completed in a day or
two, it is fit for an issue. If the task takes more than a few days, it should
probably be split into several smaller issues.
4
www.allspice.io
www.allspice.io
On the other hand, some bug fixes might take weeks to solve without any way of breaking the task into smaller
chunks.
You can add issues to other issues as dependencies, meaning that the attached issue is blocking the issue from being
closed. You would have to remove or close the attached issue before you can close the main issue.
Labels
Labels are best thought of as categories. Each issue can contain multiple labels. AllSpice has created a list of default
hardware-related labels, but you can always create your own or add to this list.
AllSpice default labels
You can use labels for any form of categorization. Still, it’s often a good idea to include a priority label to inform
everyone of how important it is to work on. It’s also a good idea to include the type of work, whether the issue
covers a bugfix, a design for manufacturing change, or is a standard feature. AllSpice has also included labels for
documentation, end-of-life, layout, firmware, or mechanical issues.
4
www.allspice.io
www.allspice.io
Milestones
Each issue can be assigned to one milestone, but each milestone can have many issues assigned to it. Milestones are
useful in a scrum process, where a number of issues have to be completed by a certain date, like a sprint. Think of
milestones as collections of issues that all should be resolved in the same relative timeframe.
AllSpice milestone page
Projects
Projects are similar to milestones in that each issue can only be assigned to one project, but a project can contain
more than one issue. Issues can be assigned to both milestones and projects, allowing you a mixture of project
management.
Projects differ from milestones in a couple of ways. Projects contain “project boards” and follow the Kanban style of
management. You can have as few as 1 project board (uncategorized) and as many boards as needed for the project.
Each project board is used to track the progress and status of the issue. It is often best to use a left-to-right
approach where the issues come in on the left as uncategorized and move to the right as progress is made. Boards
let users know if an issue is being worked on, blocked, under review, or complete. Issues are changed by manually
dragging and dropping issues from one project board to another. There is no formal organization or evaluation for
moving issues around, and it is up to the users to make sure that issues are moving to the appropriate board.
4
www.allspice.io
www.allspice.io
AllSpice project board
Projects vs. milestones
Projects are best used in development processes that are ongoing or continue longer than a traditional sprint,
whereas milestones are best used for tracking issues that will be completed in a short period, like a sprint.
There is nothing stopping you from using projects for sprints and milestones for long-term activities, but the project
boards do lend themselves to containing and organizing more issues than milestones, and the more issues you have,
the longer it is going to take to complete them.
Furthermore, milestones are traditionally used for segmenting the development and release process, with
milestones being more geared towards specific things like releasing output files like gerber and fab files or
completing a narrowly scoped set of bug fixes. Projects are usually long-lived and can help a project from its initial
design to its continual sustaining.
Since issues can be assigned to both milestones and projects, you can mix and match your project management style
and attach an issue to both, one or the other, or neither.
4
www.allspice.io
www.allspice.io
Issue integration
One of the advantages of using issues vs. a third-party tool is Issues are tightly coupled with the git workflow. You
can reference any issue using its issue number, and that will be hyperlinked. This is especially useful in design
reviews (pull requests). When you’re writing the description of a design review, you can add commands like “closes
#26” that will automatically close the issue when the design review is merged.
The following keywords all do the same thing:

close/closes/closed
fix/fixes/fixed
resolve/resolves/resolved
You can also mark issues as duplicates with the following keywords:
Duplicate
duplicate of
duplicates
duplicate issue
duplicate pull request
Summary
Whether you wish to use third-party productivity tools, or the built-in issue tracking system, you have a lot of
options and flexibility on how you manage your projects. We recommend you give the issue/milestone/project
system a try to see how much time and energy you can save using the native integrated tools.
4
www.allspice.io
www.allspice.io
Git platforms
Chapter 9: A list of git platforms to utilize

for hardware development.
Chapter 9: Git platforms
Overview
We live at the dawn of a golden age of hardware development. The tools being built are powerful, fast, and focused
on saving money and time but not necessarily with an intuitive user interface. Git has a reputation for being clunky
and severe, but everyone participating in the tool-building ecosystem has taken git a long way from its command
line-only roots. Hats off to all of these projects that push the boundaries of what git can be.
Git providers are doing more than just providing managed hosting of git servers. It is a fantastic business advantage
to have someone else maintain the servers. If you don’t have the need or requirement to host git on-site or with
internally managed servers, you can save a lot of money by working with a trusted team to keep your designs safe.
Most services are available for a low monthly cost that is a fraction of an hour’s labor for a IT professional.
In addition to creating downward pressure on operation expenses, each git service provider has contributed
features and user experience changes, some of which have become synonymous with git. Each of these
organizations puts its own spin and adds additional tools and features.
AllSpice
Allspice.io is the only tool on this list that is focused specifically for hardware development. Unlike most software
development, the source files are edited visually in electronic computer-aided drawing (ECAD) programs.
Schematics are edited as boxes, triangles, and other shapes being manually connected with wires. PCB designs are a
literal 1:1 drawing of the physical features of the PCB. Even if these values are stored in a text file, the files are
designed with a visual process.
AllSpice Hub solves this problem by creating tools for hardware revision control. When you push your changes to
the server, the hub converts the binary files into visual SVG files everyone can read. The schematics and PCB layout
SVG files are generated with color coded changes. The visual diff is easy for people of all skill levels to read with red
for deletion, green for new, and yellow for parts, nets, and silkscreen that have been changed.
4
www.allspice.io
www.allspice.io
PCB diff with changes in yellow, new items in green, and removed items in red.
4
www.allspice.io
www.allspice.io
See how easy it is to tell which capacitor has been deleted and which has been changed. You can also see that U115
pin 27 has been moved to the other side of the resistor, R108.
Schematic diff with changes in yellow, new items in green, and removed items in red.
4
www.allspice.io
www.allspice.io
You can even click on components, traces, and nets to see the available meta data. Here you can see that the value
changed from 220uF capacitor to a 470uF cap and that the part number was populated.
Schematic metadata, showing circuit attributes
Adding to the visual diff, AllSpice has implemented a snippet tool that allows you to natively highlight sections of the
designs and post them into a comment or review without needing to use an external image editing tool. Gone are
the days of reviewing PDFs full of screenshots.
4
www.allspice.io
www.allspice.io
Conversation thread using the schematic snippet tool
Allspice has also released a free, standalone diff tool to generate the visual schematics and layouts from the files and
include the color highlighted diff.
They currently support Altium Designer and OrCAD Cadence Allegro, and you can sign up for a demo.
AllSpice Hub is built on top of Gitea, so it has a robust backend with a familiar user interface, very similar to GitHub.
4
www.allspice.io
www.allspice.io
GitHub
Anyone familiar with git, knows about GitHub. 84% of the Fortune 100 use GitHub Enterprise and has over 73
million users. GitHub was creating so much value that it was acquired by Microsoft in 2018 for $7.5 billion. GitHub
has introduced many features over the years, but with the amount of competition, many of the other tool-builders
are catching up.
GitHub has many tools for your repo in its marketplace. Many organizations use third-party integrations for
(CI/CD) and other important DevOps processes.
GitHub is a wonderful tool if you’re looking for an easy experience for writing software or firmware, but if you want
to see your schematics or their changes, you’ll have to generate your own tools. This is what an Altium schematic file
looks like when you view it raw, which is the only way to detect what the file differences are between versions..
Schematic binary blob demonstrating the difficulty in merging this type of file
4
www.allspice.io
www.allspice.io
Gitea
Gittea is a free and open source git hosting platform with many of the same features as GitHub Enterprise Edition.
It’s main purpose is to be your “painless self-hosted git service”. Gitea is easy to install, but there are many hosting
services like Digital Ocean and Linode that have pre-configured turn-key servers that can start up your own git
platform. Gitea can be hosted in the cloud, or on-premises to give you control and mutability. You can either freely
change the gitea code and keep your changes local to your organization, or you can participate in the gitea project
and submit your code changes to pull requests in their open repo.
AllSpice Hub is based on a fork of gitea, so you get all the power and functionality of gitea, but with the hardware
specific features that let you see schematic changes instead of binary blobs. AllSpice has team members who write
code and submit it the project, giving back to the open source community.
Schematic binary blob
GitLab
Although often confused for GitHub, GitLab takes a different approach. GitLab features both an open source
community edition that lets you host and modify your server as you see fit, and also an Enterprise Edition. The
enterprise solution can be self-hosted or fully managed.
GitLab’s specialty is for CI/CD and has numerous built-in and turn-key services for testing, packaging, and releasing
your files. Because they are built-in, they aren’t relying on external services that you have to update and maintain.
Because they’re native, you don’t have to cobble together your own brittle integrations from scratch.
GitLab lets you automate procedures like automatically stage, test, and release kubernetes. The platform also
allows you to scale your projects and deploy more resources as the project grows.
4
www.allspice.io
www.allspice.io
GitLab also focuses on stability and has a preference for a multi-step release process, with branches feeding into
one another from pre-production, to testing, to production release servers.
GitLab is an excellent platform for software teams. There are many integrations that are helpful for firmware
development. Using a test-driven design (TDD) integration platform can test your C/C++ or machine code without
even needing production hardware. There are no integrations, however, for running firmware on native hardware.
There are no hardware integrations, however, and GitLab suffers from the same problem as all the other software-
centric platforms. You can’t see the schematic and layout design files without rolling your own solution.
GitKraken
GitKraken doesn’t offer hosting for your git projects, but it does offer one of the slickest interfaces for a git client.
You can use GitKraken to connect to a git host and use their tool to view and manage your commit history. The
visual interface makes it a lot easier to see how commits and branches are connected in the repo. While other tools
like TortoiseGit, SourceTree, and Git Cola offer up similar functionality, they don’t have the fresh UI of GitKraken.
The free tool is available for single users, and there is a paid tier for teams and enterprises.
GitKraken's branching user interface

4
www.allspice.io
www.allspice.io
text-only. You can use GitKraken in combination with AllSpice’s diff tool to generate visual diffs locally on your
machine.
Gogs
Gogs is another self-hosted git platform. Gitea is a fork of Gogs, so both platforms have a lot of similarities. Gogs
offers some interesting features like native support for Jupyter Notebook and PDF rendering.
Gogs is focused on software revision control and doesn’t have any features specifically for a hardware workflow.
Reviewing schematic and PCB diffs will be via binary blob and not with a visual schematic or view of the layout.
Bitbucket
Bitbucket is Atlassian’s solution to hosted git. Because Atlassian also produces Jira, it features tight issue tracking
and product management integration into its git tool. Most of the rest of the solutions listed here have 3rd party
integrations to issue tracking tools and can use Jira. It may be that your team needs the tighter integration of a
native tool.
Bitbucket offers fully managed hosting but also offers a self-hosted “Data Center” edition. The tool also offers
Bitbucket pipeline for automating building, test, and deployment.
Because Bitbucket is software-centric, there are no hardware tools, so schematic and layout files only have a binary
blob for review.
Yet another binary blob
4
www.allspice.io
www.allspice.io
Sourceforge
Sourceforge is one of the oldest revision control tools and has hosted many famous projects. One of the huge
downsides of Sourceforge is its business model uses advertising, and any given repo might have five or more
advertisements, cluttering and distracting from the development process. The other downside is that they don’t
support closed-source repositories. If you’re working on an open-source hardware project, you might want to
consider Sourceforge, but if your project is proprietary, you would need to consider a different platform.
AWS CodeCommit / Elastic Beanstalk

Amazon has its own managed git platform with AWS CodeCommit. It offers up many of the features of GitHub, but
with tight integration with Amazon Web Services (AWS). With the addition of Amazon’s Elastic Beanstalk, the code
can be set up to automatically create, build, and run many of Amazon’s services. This can save a lot of time for
companies that are working on a product that is running on AWS.
Neither of the solutions offers any hardware-centric tools and run into the same problems with reviewing
schematic and PCB layout diffs as many of the solutions here.
Summary
While the previous 20 years have given us many great git hosting platforms, most of them focus solely on software
projects. It’s possible to use a vanilla software platform to manage your hardware revision control, but what all of
these tools lack is the ability to view and see changes to schematics and PCB layouts. Despite many of these
companies focusing on CI/CD, the existing integrations are for building and deploying software. Most of these orgs
don’t have CI/CD for hardware on their roadmap.
AllSpice.io automatically creates visual schematics and layouts that are human-readable, offering hardware-specific
functionality that you can’t get on other platforms. Although the other tools may offer features and ease of use with
committing file changes in general, they don’t help hardware projects when it comes time for design reviews.
4
www.allspice.io
www.allspice.io
About AllSpice
AllSpice is the Git hardware development &

collaboration platform inspired by software principles.
A platform that blends documentation and

design with a flexible home base for your
hardware products
A place to bring your team together with

effortless digital & remote collaboration -
both for engineers and the rest of hardware
stakeholders
A powerful engine to automate the repetitive

tasks in your development process, to reduce
the risk of errors and get products to market
faster
We help teams accelerate their hardware development with digital, asynchronous design reviews that run like
pull requests, automated visual PCB, schematic, and BOM diffs, and the many more capabilities they need to
build an agile workflow.
4
www.allspice.io
4
www.allspice.io
© 2022 AllSpice, Inc.

Git For HW Guide 2.0

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Git For HW Guide 2.0

Uploaded by

Copyright:

Available Formats

The

14 Revision control concepts

22 Commit best practices

31 Pushing & branching

43 Design review basics

54 Generated files best practices

60 Assemblies best practices

65 Issues & milestones

Chapter 1: Why use Git for hardware?

Why Use git for hardware?

Team size and structure

Assembly lifecycle and SKU count

Legacy revision control - file systems

Product lifecycle management (PLM) systems

Revision control using Git

Atomic commits speed review

Atomic commits speed revision

Asynchronous reviews reduce meetings

Total change history

Git issues and milestones simplifies requirements tracking

Git branching is more flexible

At AllSpice, we recommend a strategy of using two-plus branches.

to this approach is manual merging if the branch proves useful.

Git has many software solutions

Vanilla git doesn’t show schematic and layout differences

Git is revision control, not PLM

Chapter 2: Revision control has made huge

Source files and output files

Commit, push, branches

Pull requests / design reviews

Chapter 3: An overview of the ways to

Commit to the correct branch

Commit related changes

“Place a block diagram of relay control ckt”

“Add voltage regulators to library”

“Add +3.3V to all powered chips”

“Add isolated optofets to relay drivers”

Commit often, perfect later

Test your design before you commit

Write good commit messages

Use the imperative mood

Imperative: If applied, this commit will

Chapter 4: Taking commit best practices

Push to the correct branch

Branching Strategy: Main and Develop

Git two-branch strategy, merging from dev branch to main branch

Branches: Keep or Delete

Branching strategy: git flow

Custom branching structure

Chapter 5: How git design reviews, also

Design review basics

AllSpice design review (PR) tab

AllSpice merge branch selection

AllSpice new design review creation process

AllSpice new design review form

Click on Create Design Review to finally create the review.

AllSpice new design review creation

This is a list of the default issues included in an AllSpice repo.

AllSpice's default labels

Repo branch protection

Repo merge blocking

Design review cautioning merging until official reviews are complete

Design review merge