| IDs | Name | Weight | Openness | Hardware | Quality | Machine-Readability | Description | Why | Source Code |
|---|---|---|---|---|---|---|---|---|---|
| bom_exists | BoM exists | 0.20 | 0.50 | 1.00 | 0.30 | 0.60 | Checks that a Bill of Materials (BoM) file exists in the projects root dir, using the regex (?i)^(BoM\|BillOfMaterials\|Bill_of_Materials\|Bill-of-Materials).*$. |
A BoM file contains a list of all required parts, be that raw parts or ready-made ones. That not only clearly marks the repository as a hardware project, but also allows for quick human (and partly machine/software) based analysis for what is needed to build the piece of hardware, and to have at east a first rought idea about the costs, and potential candidates that could become a supply problem. … plus probably many other uses. |
bom_exists.nim |
| clean_cad_files | Clean CAD files | 1.00 | 1.00 | 1.00 | 0.50 | 1.00 | Checks that the Mechanical design files - Computer Aided Design (CAD) files - if any, use an open format, are text-based and are actual source files (vs generated). |
- open format: This is good for collaboration: It is legal and technically easier to create viewers and editors, and it is much more likley that there already are or will be viewers and editors for such formats, which are free themselfs. - text-based: This is good for versioning with a version control system, e.g. git, which makes collaborating and sharing of a design easier. - source files: This is required for being Open Source in the first place. |
clean_cad_files.nim |
| clean_electronics_files | Clean electronics files | 1.00 | 1.00 | 1.00 | 0.50 | 1.00 | Checks that the contained Electronics blueprint files - Schematics and PCB designs - if any, use an open format, are text-based and are actual source files (vs generated). |
- open format: This is good for collaboration: It is legal and technically easier to create viewers and editors, and it is much more likley that there already are or will be viewers and editors for such formats, which are free themselfs. - text-based: This is good for versioning with a version control system, e.g. git, which makes collaborating and sharing of a design easier. - source files: This is required for being Open Source in the first place. |
clean_electronics_files.nim |
| license_exists | LICENSE exists | 0.20 | 1.00 | 0.00 | 0.05 | 1.00 | Checks that a LICENSE file exists in the projects root dir, using the regex (?i)^.*(LICEN[SC]E\|COPYING).*$.Note that this is related to the REUSE lint check. |
Before REUSE, this was the standard (and only) way to declare which license(s) are used within the project. While REUSE is in all ways superior to this approach, Many platforms and softwares still purely rely on this way to automatically detect the license(s) of a project. We thus recommend to keep the “main” (according ot your subjective decission) license of the project in such a file, by first fixing REUSE for the project, and then running a command similar to: cp LICENSES/CERN-OHL-S-2.0.txt LICENSE.txt |
license_exists.nim |
| markdown_lint | Markdown content | 0.50 | 0.90 | 0.00 | 1.00 | 1.00 | Checks that the content of all Markdown files in the repository adheres to a strict set of syntax rules for that format. |
Markdown exists in many different varieties. There is mostly one original format (simply: “Markdown”), which has very loose syntax rules, and which nobody uses anymore, because it can be unclear what was meant to be expressed (format wise). Then there are all the derivatives, which are not fully compatible amongst each other. Examples for these are: * CommonMark (Close) * Github Flavored Markdown (GFM) * GitLab Markdown (very similar to the above) * Pandoc Markdown CommonMark has the same, limited set of features like the original Markdown, but is very strict with regards to what is valid and what not. This is good, because it means, that if you adhere to this set of rules, your Markdown will be correctly interpreted whereever Markdown is accepted Most other Markdown flavors - like the other three above - have extended the original set of features, and try to guess what the user wanted to express, even if they did not use correct syntax. To rely on this though, makes ones Markdown less portable, and thus in a way, kind of inflicts a soft lock-in on systems supporting such heuristics. |
markdown_lint.nim |
| markup_link | Markup link check | 0.70 | 0.90 | 0.00 | 1.00 | 0.60 | Checks whether links in Markdown and HTML documents in the repo are pointing to something valid. |
Links are often put in by project maintainers once and then they forget about them. Due to the dynamic nature of the web, links become defunct over time, which of course hurts the quality of the documentation and the experience the users have, browsing it. This is especially important and freuqent in regards to repo-internal links. This check brings the attention of this issue back to the repo maintainers, without having to rely on users reporting each link individually. |
markup_link.nim |
| no_generated_files | No generated files | 0.50 | 0.60 | 0.00 | 0.50 | 0.30 | Checks that no generated files are part of the project. These are usually files that are created using a software that is manually configured and executed by a human. Try instead, to find a way to automate this process, and to not store the resulting files in the repository. |
1. The projects storage requirements go down - usually by a lot 2. There are no outdated generated files, because of either of these two reasons: - One only gets the files hwen generating them right when required, or - They are regenerated in CI/build-bot and uploaded/hosted on the project pages whenever there is a change (e.g. a git push to to the repo) NOTE: This is one of the more controversial checks, as it often requires writing new software. That is sometimes a simple script, and sometimes complex software requiring many person-months of development. |
no_generated_files.nim |
| no_global_links_to_local_files | No global links to local files | 0.40 | 0.80 | 0.00 | 0.80 | 0.80 | Checks no links to project local files use a ‘global’ prefix, be it a web-hosting URL or an absolute local path. |
This is a step towards a documentation that is: - locally browsable an editable without internet connection - showing and linking to the actual, local, correct content |
no_global_links_to_local_files.nim |
| no_sources_in_root | No sources in root | 0.10 | 0.60 | 0.00 | 0.80 | 0.00 | Checks that no source files appear in the root dir of the project. Make sure to put them all into sub-directories, for example src/. |
Makes the Repo look more clean and more friendly, especially for non-coding people that might just wnat to browse or edit the documentation. |
no_sources_in_root.nim |
| no_space_in_file_names | No space in file names | 0.40 | 0.60 | 0.00 | 0.80 | 1.00 | Checks that no file-names in the project contain white-space. | This makes automatic processing of all the projects files much easier and less error-prone. |
no_space_in_file_names.nim |
| okh_file_exists | OKH file exists | 0.70 | 1.00 | 1.00 | 0.50 | 1.00 | Checks that the OKH manifest file - which contains project meta-data - exists. |
If this is actually a hardware project, the existence of this file clearly and unmistakingly marks it as such, both for humans and machines/software. This is useful when dealing with a lot of projects, to not waste life- or processing-time, which likely would still be less exact in its findings. |
okh_file_exists.nim |
| okh_lint | OKH manifest content | 0.70 | 1.00 | 0.00 | 1.00 | 1.00 | Checks that the OKH manifest file - which contains project meta-data - contains at least the required properties, and that all properties use the correct format. |
This makes the project much more easily comparable, both for humans and machines/software. This is useful when dealing with a lot of projects, to not waste life- or processing-time, trying to figure out a certain, commonly useful set of properties about a project. |
okh_lint.nim |
| readme_exists | README exists | 0.20 | 1.00 | 0.00 | 0.10 | 0.50 | Checks that a README file exists in the projects root dir, using the regex (?i)^.*README.*$. |
A README file is the main entry point for a human that comes along the project, and wants to figure out what it is about, and how to use it. It is targeted at all potential stakeholders of the project, be it designers, manufacturers, sellers, repairers or users. We might think of it as the most essential, basic part of the documentation of the project. |
readme_exists.nim |
| reuse_lint | REUSE Licensing info | 0.50 | 1.00 | 0.00 | 0.30 | 1.00 | Checks that complete SPDX licensing info is given for all files in the project. We do this using the Free Software Foundations REUSE tool. NOTE: This is related to the License exists check. |
Copyright and licensing is difficult, especially when reusing software from different projects that are released under various different licenses. REUSE was started by the Free Software Foundation Europe (FSFE) to provide a set of recommendations to make licensing your Free Software projects easier. Not only do these recommendations make it easier for you to declare the licenses under which your works are released, but they also make it easier for a computer to understand how your project is licensed. Propper licensing information may prevent or help in potential legal disputes. It also helps anyone using your source or derivates of it, to understand their rights. |
reuse_lint.nim |
| unwanted_files_exist_not | No unwanted files | 0.50 | 0.60 | 0.00 | 0.50 | 0.30 | Checks that no unwanted files are part of the project. These could be backups, caches, IDE/platform specific, and so on. |
These files, present in the repo, could cause these issues and inconvieniences: - potentially inflating the repositories size - mess up local settings (e.g. local cache paths of an IDE) by one designer on an other deginers machine - make the project appear less clean - make the project maintainers look like amateurs to seasoned Open Source people - confuse people, as they are around, yet seem to have no usefulness |
unwanted_files_exist_not.nim |
| uses_dir_std | Uses dir standard | 1.00 | 1.00 | 0.30 | 1.00 | 1.00 | Checks whether the unixish OSH directory standard is used for a sufficient amount of files and directories in the project, using the osh-dir-std CLI tool. |
1. to be able to extract meta-data: 1. easy indexing (and thus finding) of projects 2. easy comparing of projects 3. allows to write software tools that deal with project repos 2. find your way around quickly and easily in different projects |
uses_dir_std.nim |
| vcs_public | VCS public | 0.70 | 1.00 | 0.00 | 0.60 | 0.00 | Checks whether the Version Control System (VCS) is publicly available, and without requiring authentication. |
A public VCS (e.g. a git repo on GitHub) - while somewhat challenging to use for some people - currently (May 2023) is the best way to colaboratively work on Open Source projects together. It allows to track changes in parallel, to see who did what when and why (if use right). Without a public VCS, the project develoment is reserved for “the elite” that is allowed access to it, or alternatively - and maybe even worse - the development is split up and happening in parallel, without a good way of sharing the fruits of labout of that process. |
vcs_public.nim |
| vcs_used | VCS is used | 0.70 | 1.00 | 0.00 | 0.60 | 0.80 | Checks whether a Version Control System (VCS) is used to store the projects files, e.g. git, mercurial or pijul. |
## What is a VCS Version control is a system that maintains a history of changes. What is packaged into a single, specific change, (aka commit or patch), is decided by the people that make the changes. These changes should be small and they should form logical units that make sense as a whole, to the point where it makes no sense to divide them further. A change might edit any number of files, delete some, and add others. In the VCS, each change comes complete with a summary, optional extensive description of the changes, author info, timestamp and other details. Thus, the VCS can tell you who changed what, when and why, and it allows you to go back in time, or create a new mix of changes: an alternative history. A specific change may also be marked as a version, like ‘2.0’ or ‘1.5.3-alpha’. ## What is it good for To share the product documentation on versioning systems is the most efficient, quality-rich way to work in parallel within a distributed community. Having the complete history enables going back to previous versions to help in root cause analysis for bugs and it is crucial when needing to fix problems in older versions. It allows also to connect reported bugs and project management software to the relevant change(s), which allows to see whether a particular version contains a specific fix of a bug or feature. Textual documentation can be edited online. |
vcs_used.nim |