|
|
**Welcome to community-based assessment of open source hardware!**
|
|
# Scope
|
|
|
|
|
This guide describes the workflow of the review/assessment process in the OSEGeV Conformity Assessment Body.
|
|
|
**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.
|
|
|
|
|
|
|
in rework
|
|
|
# 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.
|
|
|
|
|
|
|
**Welcome to community-based assessment of open source hardware!**
|
|
|
# The Procedure
|
|
|
|
|
|
|
**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.
|
|
|
## Overview
|
|
|
|
|
|
|
Thanks for donating your time and brain capacity for this. Highly appreciated.
|
|
|
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:
|
|
# The Scope
|
|
|
|
|
|
|
|
* `[Review][main] <project-name>`
|
|
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.
|
|
|
* 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>`
|
|
# The Procedure
|
|
|
* Here you need to check if the project is licensed appropriately. Sometimes this issue is within the main issue.
|
|
|
|
|
* `[Review][subgroup] <project-name>`
|
|
## Overview
|
|
|
* 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.
|
|
|
|
|
|
|
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.
|
|
|
All relevant discussions & decisions are directly documented in the issue as comments.
|
|
Two Issues will always be there:
|
|
|
|
|
|
|
|
## The Process
|
|
* `[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.
|
|
|
1. Get assigned:
|
|
* `[Review][License] <project-name>`
|
|
|
* to an OSH project to review and
|
|
* Here you need to check if the project is licensed appropriately. Sometimes this issue is within the main issue.
|
|
|
* to specific review issues that meet your skills and knowledge.
|
|
* `[Review][subgroup] <project-name>`
|
|
|
2. Perform review:
|
|
* 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.
|
|
|
* Check if all mandatory information is there,
|
|
|
|
|
* state misalignments otherwise and
|
|
All relevant discussions & decisions are directly documented in the issue as comments.
|
|
|
* 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:
|
|
## The Process
|
|
|
* 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,
|
|
1. Get assigned:
|
|
|
* reset the review status for the relevant issues for another revision,
|
|
* to an OSH project to review and
|
|
|
* then accept the merge request.
|
|
* to specific review issues that meet your skills and knowledge.
|
|
|
4. Approve items:
|
|
2. Perform review:
|
|
|
* Once all misalignments are resolved the items can be approved.
|
|
* Check if all mandatory information is there,
|
|
|
* Do so by ticking the checkbox assigned to you (`[ ] approved @reviewer_1` → `[x] approved @reviewer_1`).
|
|
* state misalignments otherwise and
|
|
|
5. Close issues (**not \[main\]**)
|
|
* 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!).
|
|
|
* Once all checkboxes for approval are ticked.
|
|
3. Check the update:
|
|
|
* Do not manipulate or close the **\[main\]** issue! This is for CAB Admins only.
|
|
* 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.
|
|
|
6. Have fun\\
|
|
* Check the merge request and see if all relevant issues are tagged,
|
|
|
* actually starts right after point 1
|
|
* reset the review status for the relevant issues for another revision,
|
|
|
|
|
* then accept the merge request.
|
|
|
## What to review?
|
|
4. Approve items:
|
|
|
|
|
* Once all misalignments are resolved the items can be approved.
|
|
|
### Intro
|
|
* Do so by ticking the checkbox assigned to you (`[ ] approved @reviewer_1` → `[x] approved @reviewer_1`).
|
|
|
|
|
5. Close issues (**not \[main\]**)
|
|
|
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.
|
|
* Once all checkboxes for approval are ticked.
|
|
|
|
|
* Do not manipulate or close the **\[main\]** issue! This is for CAB Admins only.
|
|
|
|
|
6. Have fun\\
|
|
|
### License
|
|
* actually starts right after point 1
|
|
|
|
|
|
|
|
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.
|
|
## What to review?
|
|
|
|
|
|
|
|
### Documentation of Hardware
|
|
### Intro
|
|
|
|
|
|
|
|
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
|
|
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.
|
|
|
|
|
|
|
|
#### Different types of parts
|
|
|
|
|
|
|
### License
|
|
|
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.
|
|
|
|
|
|
|
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.
|
|
|
##### Proprietary/Buy Parts
|
|
|
|
|
|
|
### Documentation of Hardware
|
|
|
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.
|
|
|
|
|
|
|
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
|
|
|
##### Standard Parts
|
|
|
|
|
Standard parts (such as screws, nuts, bolts....) need to be described with their accurate name. For example: DIN 965 A2 M5X40
|
|
#### Different types of parts
|
|
|
|
|
|
|
|
##### Unique 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.
|
|
|
|
|
|
|
|
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.
|
|
##### Proprietary/Buy Parts
|
|
|
|
|
|
|
|
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!
|
|
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.
|
|
|
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.
|
|
|
|
|
|
|
##### Standard Parts
|
|
|
### Software
|
|
Standard parts (such as screws, nuts, bolts....) need to be described with their accurate name. For example: DIN 965 A2 M5X40
|
|
|
In case there is Software needed for the project. Can you access it?
|
|
|
|
|
Do you understand how to use it?
|
|
##### Unique Parts
|
|
|
|
|
|
|
|
### Bill of Materials - BoM
|
|
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.
|
|
|
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.
|
|
|
|
|
|
|
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!
|
|
|
### Assembly instructions
|
|
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.
|
|
|
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?
|
|
### Software
|
|
|
Do you understand how to use the software, if there is software or firmware?
|
|
In case there is Software needed for the project. Can you access it?
|
|
|
|
|
Do you understand how to use it?
|
|
|
|
|
|
|
|
### In Short
|
|
### 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.
|
|
|
Would you be able to build and modify this hardware only by the given documentation?
|
|
|
|
|
|
|
### Assembly instructions
|
|
|
* Yes → approve
|
|
Do you understand on how to put all parts together to build the piece of hardware?
|
|
|
* No → state misalignment so it can be fixed
|
|
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?
|
|
|
# FAQ
|
|
|
|
|
|
|
|
|
|
## Does it qualify, when…
|
|
### In Short
|
|
|
|
|
|
|
|
### all information is there, but native CAD files are missing?
|
|
Would you be able to build and modify this hardware only by the given documentation?
|
|
|
|
|
|
|
|
**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.
|
|
* Yes → approve
|
|
|
|
|
* No → state misalignment so it can be fixed
|
|
|
### technical drawings are missing, but STEP exports are available?
|
|
|
|
|
|
|
# FAQ
|
|
|
**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.
|
|
|
|
|
|
|
## Does it qualify, when…
|
|
|
### a non-commerial license is used?
|
|
|
|
|
|
|
### all information is there, but native CAD files are missing?
|
|
|
**No.** (and we are getting this question way to often).\
|
|
|
|
|
See [this resource](https://mifactori.de/non-commercial-is-not-open-source/) for details.
|
|
**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.
|
|
|
|
|
|
|
|
## During Review
|
|
### technical drawings are missing, but STEP exports are available?
|
|
|
|
|
|
|
|
### What if I have feedback not related to DIN SPEC 3105-2?
|
|
**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.
|
|
|
|
|
|
|
|
…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.
|
|
### a non-commerial license is used?
|
|
|
|
|
|
|
|
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.
|
|
**No.** (and we are getting this question way to often).\
|
|
|
|
|
See [this resource](https://mifactori.de/non-commercial-is-not-open-source/) for details.
|
|
|
# Feedback
|
|
|
|
|
|
|
## During Review
|
|
|
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.
|
|
|
|
|
|
|
### What if I have feedback not related to DIN SPEC 3105-2?
|
|
|
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.
|
|
|
|
|
|
|
…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.
|
|
|
* What was your experience?
|
|
|
|
|
* What difficulties did you face?
|
|
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.
|
|
|
* How did you solve them?
|
|
|
|
|
* Was the information provied helpfull?
|
|
# Feedback
|
|
|
* What did you miss and how would you have wished it to be?\
|
|
|
|
|
Be free. Be creative. We are counting on you ⭐
|
|
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.
|
|
|
|
|
|
|
|
Some specific questions for our reviewers:
|
|
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 aspects did you review?
|
|
* What was your experience?
|
|
|
* what details did you look at?
|
|
* What difficulties did you face?
|
|
|
* was it your first review?
|
|
* How did you solve them?
|
|
|
* was the process clear to you?
|
|
* Was the information provied helpfull?
|
|
|
* did you know what to look at, what questions to answer?
|
|
* What did you miss and how would you have wished it to be?\
|
|
|
* how much time did you take?
|
|
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? |
|
* what (technical) specification of the review process would you wish for as guidance? |
|
|
|
\ No newline at end of file |
