Skip to content

Best Practices for Open-Source Hardware Projects

Here, we provide a distilled account of best practices with pointers to other resources with further information. We recommend you also read the Best Practices for Open Source Hardware published by the Open Source Hardware Association (OSHWA). Another good resource is the Electronics Design project in the Open Hardware Repository. It provides e.g. checklists for design reviews.

It is very important to follow best practices when you open-source your hardware designs. The OSPO will check before issuing a recommendation to open-source, and we will provide guidance to projects on ways to achieve the necessary level of quality.

The entry point

It is good to have a single entry point for your project on the Web, where people can quickly find basic information, including:

  • A short description of the project.
  • A bullet list of features.
  • A picture if available, or a render from the CAD tool if the hardware is not yet produced.
  • Pointers to the design files and documentation.
  • Pointers to other relevant documents. See here for an example PCB flow which includes documents such as the specifications and the outcomes of various reviews.
  • A list of commercial vendors. See below for more detail on the role of companies in a typical OSHW project.
  • A status table. This is a quick way for everyone to see what is the current state of the project. Are specifications ready? Have you already had prototypes produced?
  • Team members and contact information.
  • Links to the issue management system (see below) and to any forums where public discussions happen for the project.

One way to implement the above is to use the main wiki page of the collaboration space (GitHub, GitLab...) for the project. See the SPEC board designed at CERN for an example of such an entry page.

Notice that, even if your design files may not be hosted in the repository associated with your collaboration space, it is still a very good idea to have that space as your main entry point as well as for managing issues and communication, as described below.

Issue management

The issue management part of your collaboration platform can be used in exactly the same way as for software projects, to make sure you have a written trace of issues identified during reviews and tests, to have issues grouped under a given milestone, and to facilitate communication inside the team and with the outside world. See the issue tracking section of this website for further guidance.

Communication

Sometimes we need a way to communicate within the community of those interested in a given hardware design, beyond the basic communication provided by issue management and Merge Request / Pull Request Web interfaces. One good way is to provide a forum (see example for the White Rabbit project) which is linked to from the project entry page. See the community discussions section for more on this important subject.

Finding companies to work with

As pointed out in key concepts, companies are an essential ingredient in OSHW. See "Working with companies" in our howto guides for more details.

Production Test System

One important ingredient in the overall quality and commercial strategy for OSHW designs is the Production Test System (PTS). Ideally, when you order PCBs from a company, you also send them the PTS so that they can test every unit in an automated manner after production. In that way, you only receive hardware which has passed the tests. This liberates you from this task and improves the overall quality of your project. The flip side is that you need to include PTS development in your plans from the beginning of the project. Sometimes, the PTS itself will require dedicated hardware designs. These designs can be made open source following the same good practices as those used for the main design.