|
|
**Welcome to community-based assessment of open source hardware!**
|
|
|
|
|
|
**You, the reviewer**, are part of this pilot of decentralised, transparent and community-driven quality control of documentation for open source hardware (OSH). We believe that this procedure (standardised by [DIN SPEC 3105-2](https://din.one/pages/viewpage.action?pageId=36603167)) contributes to the overall trustworthiness and applicability of open source hardware. As a side effect we hope this helps OSH projects to interconnect to each other.
|
|
|
|
|
|
Thanks for donating your time and brain capacity for this. Highly appreciated.
|
|
|
|
|
|
# The Scope
|
|
|
|
|
|
By your review you'll assess whether a certain piece of hardware qualifies as open source hardware according to [DIN SPEC 3105-1](https://din.one/pages/viewpage.action?pageId=36603169). See [CAB overview](3-Further-Information/CAB) or [DIN SPEC 3105-1](https://din.one/pages/viewpage.action?pageId=36603169) for more general information.
|
|
|
|
|
|
# The Procedure
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
Review happens in corresponding issues on the CAB's GitLab instance. They should be self-explanatory and may differ based on the projects structure. Usually we divide projects in different subgroups so you can go through the project step by step.
|
|
|
Two Issues will always be there:
|
|
|
|
|
|
* `[Review][main] <project-name>`
|
|
|
* that's just for the overview; no need to do anything here; however, you're free to view and comment general things, especially to give recommendations for the project development beyond the requirements of the assessment.
|
|
|
* `[Review][License] <project-name>`
|
|
|
* Here you need to check if the project is licensed appropriately. Sometimes this issue is within the main issue.
|
|
|
* `[Review][subgroup] <project-name>`
|
|
|
* Here you will start checking if enough information is available to purchase all parts of the sub assembly, if the appropriate files are delivered for rebuilding and if the assembly instruction is sufficient and understandable. For more detailed information on what to check, see the section [What to Review](#what-to-review) below.
|
|
|
|
|
|
All relevant discussions & decisions are directly documented in the issue as comments.
|
|
|
|
|
|
## The Process
|
|
|
|
|
|
1. Get assigned:
|
|
|
* to an OSH project to review and
|
|
|
* to specific review issues that meet your skills and knowledge.
|
|
|
2. Perform review:
|
|
|
* Check if all mandatory information is there,
|
|
|
* state misalignments otherwise and
|
|
|
* wait until misalignments are fixed (most likely by developers of the applying OSH project) or quickly fix it yourself (please refer to the [application guide](/2-Guides/application-guide) before!).
|
|
|
3. Check the update:
|
|
|
* Fixes by the applicants (applying project developers) in reply to your comments are commited as **merge requests**, ideally each one linked to the relevant issue.
|
|
|
* Check the merge request and see if all relevant issues are tagged,
|
|
|
* reset the review status for the relevant issues for another revision,
|
|
|
* then accept the merge request.
|
|
|
4. Approve items:
|
|
|
* Once all misalignments are resolved the items can be approved.
|
|
|
* Do so by ticking the checkbox assigned to you (`[ ] approved @reviewer_1` → `[x] approved @reviewer_1`).
|
|
|
5. Close issues (**not \[main\]**)
|
|
|
* Once all checkboxes for approval are ticked.
|
|
|
* Do not manipulate or close the **\[main\]** issue! This is for CAB Admins only.
|
|
|
6. Have fun\\
|
|
|
* actually starts right after point 1
|
|
|
|
|
|
## What to review?
|
|
|
|
|
|
### Intro
|
|
|
|
|
|
What makes open source hardware different from prorietary hardware is it's technical documentation. DIN SPEC 3105 is the first official standard defining concrete requirements (DIN SPEC 3105-1) and how to check them (DIN SPEC 3105-2). It is itself the first official open source standard. Hence, if you find some requirements overly demanding, too vague, missing etc. file an issue or merge request in the original repository ([https://gitlab.com/OSEGermany/OHS](https://gitlab.com/OSEGermany/OHS)) so we, the community, can take care of it.
|
|
|
|
|
|
|
|
|
### License
|
|
|
|
|
|
The License must be compliant to the [OSHWA definition](https://www.oshwa.org/definition). We maintain a [list of compliant licenses](3-Further-Information/OSH-licenses); ask a CAB Admin for help if needed.
|
|
|
|
|
|
### Documentation of Hardware
|
|
|
|
|
|
1. The documentation must be permanently and publicly accessible. When you are seeing this OSH project on [https://gitlab.opensourceecology.de/](https://gitlab.opensourceecology.de/) this is already the case
|
|
|
|
|
|
#### Different types of parts
|
|
|
|
|
|
Engineers shall be enabled to fully understand, build and modify the design only by the given documentation. So for different types of parts different information must be provided.
|
|
|
|
|
|
##### Proprietary/Buy Parts
|
|
|
|
|
|
It needs to be clear from the description of the part what you should buy. Links to Online Retailers are nut sufficient because the links can expire and then all information is lost. However they are nice to have to get a first idea of the part.
|
|
|
|
|
|
##### Standard Parts
|
|
|
Standard parts (such as screws, nuts, bolts....) need to be described with their accurate name. For example: DIN 965 A2 M5X40
|
|
|
|
|
|
##### Unique Parts
|
|
|
|
|
|
The parts individual to the project are also Open Source Hardware. The design files must be provided in their original file format and a generally accessible export format so that users a) can modify the documentation and b) have a fair chance to access the information without special or expensive software.
|
|
|
|
|
|
The format of sources and exports can vary. The source files depend on the CAD or PCB software used. Export formats should depend on the use case. For 3D-printed parts .stl or .step parts are most useful, while for milled or lathed parts technical drawings in PDF-format are most useful. Additionally there might be files to directly manufacture them. Please check if at least export format and source file is there for every part!
|
|
|
If the project uses FreeCad as CAD software it is enough to have only the source hence everybody can open this files with the free software.
|
|
|
|
|
|
### Software
|
|
|
In case there is Software needed for the project. Can you access it?
|
|
|
Do you understand how to use it?
|
|
|
|
|
|
### Bill of Materials - BoM
|
|
|
Is there a list of Materials mentioning all parts need to build the project? Do you understand it and is there sufficient description for each part.
|
|
|
|
|
|
### Assembly instructions
|
|
|
Do you understand on how to put all parts together to build the piece of hardware?
|
|
|
Are parts mentioned that you did not encounter in the BoM?
|
|
|
Do you understand how to use the software, if there is software or firmware?
|
|
|
|
|
|
|
|
|
### In Short
|
|
|
|
|
|
Would you be able to build and modify this hardware only by the given documentation?
|
|
|
|
|
|
* Yes → approve
|
|
|
* No → state misalignment so it can be fixed
|
|
|
|
|
|
# FAQ
|
|
|
|
|
|
## Does it qualify, when…
|
|
|
|
|
|
### all information is there, but native CAD files are missing?
|
|
|
|
|
|
**No.** Native CAD files are necessary to edit the design without the need of partly re-engineering it. It's an essential property of OSH to enable others to develop it further. OSH ≠ DIY.
|
|
|
|
|
|
### technical drawings are missing, but STEP exports are available?
|
|
|
|
|
|
**Yes.** **IF** the STEP files contain all necessary information (which can be critical when e.g. essential tolerances are needed). Technical drawings are highly recommended (for mechanical hardware), but currently not mandatory, when there's another suitable export available, e.g. STEP.
|
|
|
|
|
|
### a non-commerial license is used?
|
|
|
|
|
|
**No.** (and we are getting this question way to often).\
|
|
|
See [this resource](https://mifactori.de/non-commercial-is-not-open-source/) for details.
|
|
|
|
|
|
## During Review
|
|
|
|
|
|
### What if I have feedback not related to DIN SPEC 3105-2?
|
|
|
|
|
|
…e.g. technical feedback like "this part could much easier be 3D printed instead of being casted" or relevant, but optional feedback on the documentation like "measure XY is missing in drawing", when there's a STEP export making the information already accessible.
|
|
|
|
|
|
Short answer: File upstream. You can comment that in the review (since this may relevant for other reviewers as well). More important is to report this in the original repository so the developers can take care of it. If you're struggling with it or don't find the time, CAB admins are always there to help you out.
|
|
|
|
|
|
# Feedback
|
|
|
|
|
|
The workflow is still under development. Frankly speaking, since it is open source, it will always be an evolutional process, which is one of the strengths of the community driven design.
|
|
|
|
|
|
Therefore we invite you to contribute in our development. First of all we would highly appreciate your feedback on all your workflow experiences. Please feel free to create as many issues as you like inside here: [CAB Feedback](https://gitlab.opensourceecology.de/verein/projekte/cab/CAB/-/milestones/4)-Area.
|
|
|
|
|
|
* What was your experience?
|
|
|
* What difficulties did you face?
|
|
|
* How did you solve them?
|
|
|
* Was the information provied helpfull?
|
|
|
* What did you miss and how would you have wished it to be?\
|
|
|
Be free. Be creative. We are counting on you ⭐
|
|
|
|
|
|
Some specific questions for our reviewers:
|
|
|
|
|
|
* what aspects did you review?
|
|
|
* what details did you look at?
|
|
|
* was it your first review?
|
|
|
* was the process clear to you?
|
|
|
* did you know what to look at, what questions to answer?
|
|
|
* how much time did you take?
|
|
|
# Scope
|
|
|
This guide describes the workflow of the review/assessment process in the OSEGeV Conformity Assessment Body.
|
|
|
|
|
|
----
|
|
|
|
|
|
in rework
|
|
|
|
|
|
---
|
|
|
|
|
|
**Welcome to community-based assessment of open source hardware!**
|
|
|
|
|
|
**You, the reviewer**, are part of this pilot of decentralised, transparent and community-driven quality control of documentation for open source hardware (OSH). We believe that this procedure (standardised by [DIN SPEC 3105-2](https://din.one/pages/viewpage.action?pageId=36603167)) contributes to the overall trustworthiness and applicability of open source hardware. As a side effect we hope this helps OSH projects to interconnect to each other.
|
|
|
|
|
|
Thanks for donating your time and brain capacity for this. Highly appreciated.
|
|
|
|
|
|
# The Scope
|
|
|
|
|
|
By your review you'll assess whether a certain piece of hardware qualifies as open source hardware according to [DIN SPEC 3105-1](https://din.one/pages/viewpage.action?pageId=36603169). See [CAB overview](3-Further-Information/CAB) or [DIN SPEC 3105-1](https://din.one/pages/viewpage.action?pageId=36603169) for more general information.
|
|
|
|
|
|
# The Procedure
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
Review happens in corresponding issues on the CAB's GitLab instance. They should be self-explanatory and may differ based on the projects structure. Usually we divide projects in different subgroups so you can go through the project step by step.
|
|
|
Two Issues will always be there:
|
|
|
|
|
|
* `[Review][main] <project-name>`
|
|
|
* that's just for the overview; no need to do anything here; however, you're free to view and comment general things, especially to give recommendations for the project development beyond the requirements of the assessment.
|
|
|
* `[Review][License] <project-name>`
|
|
|
* Here you need to check if the project is licensed appropriately. Sometimes this issue is within the main issue.
|
|
|
* `[Review][subgroup] <project-name>`
|
|
|
* Here you will start checking if enough information is available to purchase all parts of the sub assembly, if the appropriate files are delivered for rebuilding and if the assembly instruction is sufficient and understandable. For more detailed information on what to check, see the section [What to Review](#what-to-review) below.
|
|
|
|
|
|
All relevant discussions & decisions are directly documented in the issue as comments.
|
|
|
|
|
|
## The Process
|
|
|
|
|
|
1. Get assigned:
|
|
|
* to an OSH project to review and
|
|
|
* to specific review issues that meet your skills and knowledge.
|
|
|
2. Perform review:
|
|
|
* Check if all mandatory information is there,
|
|
|
* state misalignments otherwise and
|
|
|
* wait until misalignments are fixed (most likely by developers of the applying OSH project) or quickly fix it yourself (please refer to the [application guide](/2-Guides/application-guide) before!).
|
|
|
3. Check the update:
|
|
|
* Fixes by the applicants (applying project developers) in reply to your comments are commited as **merge requests**, ideally each one linked to the relevant issue.
|
|
|
* Check the merge request and see if all relevant issues are tagged,
|
|
|
* reset the review status for the relevant issues for another revision,
|
|
|
* then accept the merge request.
|
|
|
4. Approve items:
|
|
|
* Once all misalignments are resolved the items can be approved.
|
|
|
* Do so by ticking the checkbox assigned to you (`[ ] approved @reviewer_1` → `[x] approved @reviewer_1`).
|
|
|
5. Close issues (**not \[main\]**)
|
|
|
* Once all checkboxes for approval are ticked.
|
|
|
* Do not manipulate or close the **\[main\]** issue! This is for CAB Admins only.
|
|
|
6. Have fun\\
|
|
|
* actually starts right after point 1
|
|
|
|
|
|
## What to review?
|
|
|
|
|
|
### Intro
|
|
|
|
|
|
What makes open source hardware different from prorietary hardware is it's technical documentation. DIN SPEC 3105 is the first official standard defining concrete requirements (DIN SPEC 3105-1) and how to check them (DIN SPEC 3105-2). It is itself the first official open source standard. Hence, if you find some requirements overly demanding, too vague, missing etc. file an issue or merge request in the original repository ([https://gitlab.com/OSEGermany/OHS](https://gitlab.com/OSEGermany/OHS)) so we, the community, can take care of it.
|
|
|
|
|
|
|
|
|
### License
|
|
|
|
|
|
The License must be compliant to the [OSHWA definition](https://www.oshwa.org/definition). We maintain a [list of compliant licenses](3-Further-Information/OSH-licenses); ask a CAB Admin for help if needed.
|
|
|
|
|
|
### Documentation of Hardware
|
|
|
|
|
|
1. The documentation must be permanently and publicly accessible. When you are seeing this OSH project on [https://gitlab.opensourceecology.de/](https://gitlab.opensourceecology.de/) this is already the case
|
|
|
|
|
|
#### Different types of parts
|
|
|
|
|
|
Engineers shall be enabled to fully understand, build and modify the design only by the given documentation. So for different types of parts different information must be provided.
|
|
|
|
|
|
##### Proprietary/Buy Parts
|
|
|
|
|
|
It needs to be clear from the description of the part what you should buy. Links to Online Retailers are nut sufficient because the links can expire and then all information is lost. However they are nice to have to get a first idea of the part.
|
|
|
|
|
|
##### Standard Parts
|
|
|
Standard parts (such as screws, nuts, bolts....) need to be described with their accurate name. For example: DIN 965 A2 M5X40
|
|
|
|
|
|
##### Unique Parts
|
|
|
|
|
|
The parts individual to the project are also Open Source Hardware. The design files must be provided in their original file format and a generally accessible export format so that users a) can modify the documentation and b) have a fair chance to access the information without special or expensive software.
|
|
|
|
|
|
The format of sources and exports can vary. The source files depend on the CAD or PCB software used. Export formats should depend on the use case. For 3D-printed parts .stl or .step parts are most useful, while for milled or lathed parts technical drawings in PDF-format are most useful. Additionally there might be files to directly manufacture them. Please check if at least export format and source file is there for every part!
|
|
|
If the project uses FreeCad as CAD software it is enough to have only the source hence everybody can open this files with the free software.
|
|
|
|
|
|
### Software
|
|
|
In case there is Software needed for the project. Can you access it?
|
|
|
Do you understand how to use it?
|
|
|
|
|
|
### Bill of Materials - BoM
|
|
|
Is there a list of Materials mentioning all parts need to build the project? Do you understand it and is there sufficient description for each part.
|
|
|
|
|
|
### Assembly instructions
|
|
|
Do you understand on how to put all parts together to build the piece of hardware?
|
|
|
Are parts mentioned that you did not encounter in the BoM?
|
|
|
Do you understand how to use the software, if there is software or firmware?
|
|
|
|
|
|
|
|
|
### In Short
|
|
|
|
|
|
Would you be able to build and modify this hardware only by the given documentation?
|
|
|
|
|
|
* Yes → approve
|
|
|
* No → state misalignment so it can be fixed
|
|
|
|
|
|
# FAQ
|
|
|
|
|
|
## Does it qualify, when…
|
|
|
|
|
|
### all information is there, but native CAD files are missing?
|
|
|
|
|
|
**No.** Native CAD files are necessary to edit the design without the need of partly re-engineering it. It's an essential property of OSH to enable others to develop it further. OSH ≠ DIY.
|
|
|
|
|
|
### technical drawings are missing, but STEP exports are available?
|
|
|
|
|
|
**Yes.** **IF** the STEP files contain all necessary information (which can be critical when e.g. essential tolerances are needed). Technical drawings are highly recommended (for mechanical hardware), but currently not mandatory, when there's another suitable export available, e.g. STEP.
|
|
|
|
|
|
### a non-commerial license is used?
|
|
|
|
|
|
**No.** (and we are getting this question way to often).\
|
|
|
See [this resource](https://mifactori.de/non-commercial-is-not-open-source/) for details.
|
|
|
|
|
|
## During Review
|
|
|
|
|
|
### What if I have feedback not related to DIN SPEC 3105-2?
|
|
|
|
|
|
…e.g. technical feedback like "this part could much easier be 3D printed instead of being casted" or relevant, but optional feedback on the documentation like "measure XY is missing in drawing", when there's a STEP export making the information already accessible.
|
|
|
|
|
|
Short answer: File upstream. You can comment that in the review (since this may relevant for other reviewers as well). More important is to report this in the original repository so the developers can take care of it. If you're struggling with it or don't find the time, CAB admins are always there to help you out.
|
|
|
|
|
|
# Feedback
|
|
|
|
|
|
The workflow is still under development. Frankly speaking, since it is open source, it will always be an evolutional process, which is one of the strengths of the community driven design.
|
|
|
|
|
|
Therefore we invite you to contribute in our development. First of all we would highly appreciate your feedback on all your workflow experiences. Please feel free to create as many issues as you like inside here: [CAB Feedback](https://gitlab.opensourceecology.de/verein/projekte/cab/CAB/-/milestones/4)-Area.
|
|
|
|
|
|
* What was your experience?
|
|
|
* What difficulties did you face?
|
|
|
* How did you solve them?
|
|
|
* Was the information provied helpfull?
|
|
|
* What did you miss and how would you have wished it to be?\
|
|
|
Be free. Be creative. We are counting on you ⭐
|
|
|
|
|
|
Some specific questions for our reviewers:
|
|
|
|
|
|
* what aspects did you review?
|
|
|
* what details did you look at?
|
|
|
* was it your first review?
|
|
|
* was the process clear to you?
|
|
|
* did you know what to look at, what questions to answer?
|
|
|
* how much time did you take?
|
|
|
* what (technical) specification of the review process would you wish for as guidance? |
|
|
\ No newline at end of file |