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. Using issues and milestones within Git for hardware is key.

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.

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.

Anyone can comment on an issue and leave advice, 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. 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.

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.

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 time frame.

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.

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. Project boards, however, do lend themselves to containing and organizing more issues than milestones. 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.

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.