Overview

Revision control is a continuous process, with every change and edit tracked, allowing you to pick and choose each of these edits to create a new change. Meanwhile, releases give the ability to point to a specific moment in the change history without ambiguity.

This is especially important in hardware development as actual physical things must be fabricated and assembled. Unlike software in which updates can be easily loaded, once a physical object is rendered or shipped off into the field, it has limited ability to change or update.

Releases help everyone working on the project know when files are ready for production. Although any number of commits can change the form, fit, or function of a product, the release process points to a set of files with the intended set of form, fit, or function changes.

The easiest way to understand releases is that a release points to a specific commit or design review with any number of attached files for download. The source code from that commit is also automatically included in a zip file.

Binary files

Another reason for using releases is that it’s not always a good idea to track binary or rendered files. Revision control is often referred to as source control, where the source files are tracked with every change, but output files are not. This is because the binaries or readable output files change a lot between commits. The binary files are not humanly readable, and the readable output files aren’t necessarily important, relevant, or useful to check during each commit or Design Review.

When to track files between releases

Hardware development tends to have more types of output files that users may wish to keep track of in commits. Some users might decide to only include Gerber files in releases, whereas other teams might use every change in Gerber files as part of a Continuous Integration, Continuous Deployment (CI/CD) process.

Your team might decide that schematic review tools are more than enough for revision tracking and generate PDF schematics only for releases. In contrast, other teams might decide that each commit includes generated PDFs for more holistic snapshots. The tradeoff results in extra time downloading changes and sorting through changes to review. Some teams may understand the performance hit to productivity but have an extremely high need for quality. Some industries actually require these changes to be tracked for compliance. Ultimately, it’s a mix of business requirements and team preferences.

Which files to track between releases

The hardware development process generates lots of different outputs, so no list is exhaustive. These are files that should definitely be in a release but might not be tracked in the repo.

Assembly information
Upper-level assembly repo
Lower-level assembly repos as folders, submodules, or subtrees
Assembly instructions
Cable harnesses
Mounting hardware
Enclosures
Packaging
Printed material
User instructions
Promotional materials
Production Firmware
Manufacturing information
Gerbers
Drill files
Part position files (xy)
Fabrication specifications
Bills of Material (BOM)
Reference designator location
Cost of Goods Sold (COGS)
Verification or validation
Test procedures
Test station
Test software
Test firmware
Reference
Schematics
Datasheets

Releases versus Tags

The simplest difference between releases and tags is that releases allow you to attach files to the release, Release Workflow and tags are just references to specific commits.

There is a lot of flexibility between using release versus tags:

Some groups only use releases and ignore tags.
Some users will generate releases only from tags.
Some generate releases without a tag. It is likely that your team will use a mixture of some releases being created from a tag and others created without.

Tags can be used in many different ways, from capturing the branch name and feature development, or the design intent, such as “TestNewRadioFrequencies”.

You may want to create a release with files, but signify that the files are not ready for production by using a pre-release. While pre-releases may be created from commits to the main branch, it is a bad idea to create releases from a development branch. Releases should only be created from the main branch.

Tags cannot be updated after they are created. Releases, however, can be edited to provide more information. Files can be added or deleted.

Release Workflow

This is the simplest release workflow:

Create edits
Commit changes
Resolve conflicts
Push changes
Create Design Review
Perform Design Review
- Update with requested changes
  - Create edits
  - Commit changes
  - Resolve conflicts
  - Push changes
- Approve Design Review
- Merge changes to main
Create tag (Optional)
Create release from tag
Attach files to release
Distribute release Link

When following a hardware release flow, it’s essential to continuously track every change and edit made to the project. Use release management to point to a specific moment in the change history without ambiguity, making it easy to identify when files are ready for production. This aids in ensuring that the final product is built to specifications by including any intended changes in the release process.

Revision naming conventions

The software version convention is “vX.Y.Z” (i.e “v1.2.4”), but tags can include more descriptive references that show the intent of the tag. Some orgs may wish to retain this legacy style. However, some orgs may realize that users might not understand the difference between v3.1.2 and v3.1.3 and use a more human-readable tag.
Some organizations use “Rev/rev” instead of “v/ver/version”. It is often best to continue using whichever naming convention is already in use.
Hardware often has integer rev numbers (i.e. 1,3, or 17) and skips minor revision numbers (1.1.0, 3.1.4, 17.0.7). For things like printed circuit boards, integer revisions can make sense. A PCB assembly, however, might have minor revision numbers as some components might be removed or not installed, alternate parts used, white wires added to change the schematic netlist, or other changes that happen after the circuit board is fabricated. Any naming convention can be used effectively as long as the team agrees on the format and usage.

Conclusion

Hardware releases are the backbone of successful hardware development, allowing you to track changes and ensure the final product is built to specifications. Taking steps such as creating hardware tags can ensure that your development team is provided with a clear set of files to fabricate, assemble, and use your product. By mastering release management, you can feel confident in the quality and accuracy of your work and bring your projects to life with ease. So, let’s get excited about the power of hardware releases and all the fantastic things we can create!