End-to-End Tracking of Your PCB Design
Have you ever run a board re-spin only to discover you’re not even sure what the changes were? I’m not talking about comparing GERBERs from Rev A to Rev B, rather I am referring to understanding the requirements that drove the changes, the reason behind the changes, and all the dialog that was happening around the changes. For most of us we capture these details via email, commit history in our version control system (e.g. Subversion, Perforce, ClearCase, etc.), or in a notebook. For large, collaborative teams, these methods aren’t always good enough. In this article we explore an elegant, yet simple, way of tracking your design changes and keeping them transparent for the whole team to see and participate in. Additionally, this methodology does not limit itself to just design changes but the whole design process from requirements gathering all the way to manufacturing.
But the back of my napkin is good enough!
There are many different systems that one can use to manage and track tasks associated with their design. A classic and most fundamental example of this is a checklist. Though it may sound primitive, the old-fashioned checklist has been used for quite some time and made a spectacular reappearance in the 21st century thanks to Atul Gawande in The Checklist Manifesto. Luckily, the purpose of this article is not to convince you to use a checklist… at least not the paper version. More sophisticated checklists, or tracking systems in this case, exist in fancy web front-ends written in Angular or React so they look great but are still (fairly) simple to use (e.g. Jira, Bugzilla, Trello, etc.). You may ask the following, “The back of my napkin (covered in taco grease) works just fine. Why go through the bother of using an online system?” Working from the back of a napkin, notebook, or even a text document on your local hard drive does not enable you to take advantage of real-time collaboration, decentralized tracking, and divide-and-conquer strategies.
The case for more sophistication
You’ve heard it plenty of times: as designs become more sophisticated people need newer, more sophisticated systems. As systems become more sophisticated people get fed up and beg for simpler systems. Simpler systems eventually can’t support sophisticated designs so more sophisticated systems are reinstated and the cycle just repeats itself.
Figure 1: Sophistication vs. Complex Systems Cycle
Just like anything in engineering the true solution is found with trade-offs and compromise. We need a system with a little more sophistication and some added complexity, yet not too much sophistication so that we can use the system without pulling our hair out. When a team is able to effectively use a centralized tracking system, the benefits to a collaborative environment really start to show and you can start to take advantage of the three pillars of collaboration:
Figure 2: The three pillars of collaboration
Following the three pillars of collaboration enables everyone who is part of your design cycle can contribute and share the tasks with you. Users are able to update their status in real-time into a single place (real-time contributions), view the status of each others work without sending nagging emails to the project manager (decentralized tracking), and split the load up of design efficiently and effectively (divide-and-conquer). Again, there are many ways to skin the cat and an Excel spreadsheet on a network drive may work for you (though good luck not overwriting each other). This article merely proposes one solution that has been proven to work in multiple workplaces and completely different environments.
The solution
The solution presented in this article uses Jira as the issue/requirements tracking system, Bitbucket as the version control system, and Altium ® for the schematic capture/layout tool. Honestly, any tool that enables you to get this job done is fine. A hammer is a hammer and the tools presented here worked out well for my teams across multiple workplaces, industries, and environments. Other tools that follow this framework may work just as well (or better) for you.
The first key is to commit early and commit often. You want to check in your design early in the development and continue to check in any design changes, major or minor, as often as possible. In our setup we use Bitbucket server (a Git repository) in conjunction with the built in Git tools in Altium. This makes committing to and reviewing a managed design much easier (versus an external check-in tool like TortoiseSVN).
Figure 3: Git commit using Altium /Altium
Figure 4: Git commit history in Bitbucket linking to the Jira issues
Figure 5: Comparison of versions of Git history within Altium /
When using a tool with built in check-in capabilities the committing is rather straightforward but the key to “meaningful” commits (and commit messages), is linking them to an issue that you are tracking. For example, you’ve just got your prototype boards back and discovered on the bench that you undersized your power supply circuit. You haywire in the correct circuit, test it out, and are now ready to update your schematic. When you, or whoever is doing your board bring-up, discover the failure mode in your design, you capture that as an issue/ticket right away. In the case of this article we use Jira for creating and tracking issues.
Figure 6: Example of a simple Jira ticket
Within that ticket you now have all the information you need to fix and validate the issue you are facing. For transparency purposes you want to keep all the conversation and documentation pertaining to the issue in that particular ticket. This will enable you to collaborate effectively with your team without meaningless meetings or even worse, “Death by Reply to All” emails. Now here comes the best part: the commit history: when you link your commits to an issue you can now view every change in the design, every step throughout that process, in the issue itself. The Jira ticket now becomes the center of activity for making those changes happen in a collaborative fashion.
Figure 7: Git commit history represented in Jira ticket
You can now take this principle one step further with requirements in Jira itself. One can create each Jira task item as a requirement and start to build up the full system of requirements to complete that project. This can be as simple as:
1. Design Schematic
2. Board Layout
3. Firmware Development
Or it can be broken down into a more detailed approach:
1. Design power supply circuit with 28V-40V input and 3.3V output
a. Simulate circuit
b. Circuit design schematic capture
2. Design spacewire core with TMR
a. HDL code development
b. Generate constrained random testbench
c. Circuit design schematic capture
d. Test with simulated hardware
Figure 8: Example of Jira issue with sub-tasks
Regardless of what method you use to break down your tasks you are now able to reference these tasks in a very clear fashion and point to, in a single place, where your design requirements and changes occurred.
Conclusion
Many people have different systems in which they track design changes or requirements. This article presented a simple, yet elegant, way to capture all these requirements and view design changes in a single location. More than just basic commit history, or glorified shared spreadsheets this narrows down code commits to requirements, and rich conversations that occur between the designers. This process, in turn, enables the designers to work in a more effective and collaborative fashion.
