hoijui / osh-dir-std

Open Source Hardware directory standard(s)

OSH project directory structure standards

Motivation

Why do we need directory standards?

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

Standards documented in this repo

• Prusaish: Promotes a practical, minimal style, with emphasis on sources, and git sub-modules for firmware and scripts. Most directories are named after the file-type (i.e. suffix or software) they contain.

• Unixish (favored): Each sub-part (aka module) is in a sub-directory of its own, and internally uses the same structure like in the project root, recursively. Most directories are named after the abstract/generic function of their content.

Other structure templates

• https://www.sciencedirect.com/journal/hardwarex
• https://osf.io/wgk7q/

License

The most relevant content of this repo is licensed under the GFDL-1.3-or-later. use the REUSE tool (reuse spdx) for more details.

Funding

This project was funded by the European Regional Development Fund (ERDF) in the context of the INTERFACER Project, from January 2022 (project start) until March 2023.

osh-dir-std's Issues

Add more tags

As of now (mid March 2023),
the only tags we support/supply are bom and license.

Possible additions:

• generated
• image
• asset
• untracked
• normative
• module-root

Should `gen/` files always be a reference for `doc/` or is the manual output rather put under `res/`?

Link to Rust library&CLI for this standard in the README

Where to put different (tabular) data files?

Type of files

Two specific types I am thinking of:

• gathered data from:
  • measurements
  • simulations which are too costly to run on the fly or (often) in CI
  • interviews
  • survey
• manually assembled data, like:
  • a list of file extensions, with info denoting whether they are text or binary formats
  • A CSV table describing a standard, like the ones in the repo

Storage locations - Ideation

1. A separate data folder
   • data/measurement/forcesX.csv
   • data/simulation/stress1.csv
   • data/simulation/stress2.csv
   • data/survey1.csv
2. A sub-folder under res
   • res/data/measurement/forcesX.csv
   • res/data/simulation/stress1.csv
   • res/data/simulation/stress2.csv
   • res/data/survey1.csv

General or specific folder name(s)

data is of course a very general term, that strictly speaking,
would apply to almost anything in a repo anyway.
something like sheet or tabular on the other hand,
seems too specific and overly-focused on the format,
which is assumed to be 2D table,
while we might also want to include more (or less) dimensions then 2.

organise definition.csv alphabetically

REUSE like system for (OSH related) file-meta-data?

Instead of (or in addition to) this dir standard.

In REUSE (which is limited to licensing related file centered meta-data),
meta-data related to a file can be in 1 of three places,
with the following priorities (from highest to lowest):

1. in the header of the file its-self, if it supports comments
2. In a file with the additional extension .license and otherwise the same name, eg. my-doc.pdf.license
3. In a repo-global file: .reuse/dep5

We could almost ... reuse ( ;-) ) this whole thing as-is - I would say - except that we should probably use a more general file extension then .license. That extension should rather indicate that it contains general meta-data for the file, so it would not be limited to licensing and/or OSH, but to whatever. I Made a proposal with REUSE for this, to make their system more reusable.

In the end, what this would mean for us, is that we would get the power of tags, vs only categories and sub-categories we have with a pure directory standard.
I can already see now. that we are running into very deep and complex debates about how the structure should be and why, and that often, there are simply no optimal solutions, because many files .. in a way, should be in multiple places, or it is unclear where they should be, and files that should be together in one way of looking at it, should not be together (in the same sub-dir) in an other way of looking at it .... and all this, in the end, means we get way too much complexity. We will end up with a highly complex, bureaucratic system, that only machines are able to get right, while they can not have all the info they need to do it right. People on the other hand will never know where to look for or put files, and will end up looking for them in the whole, deep, complex tree we prescribed to the repo. For a little idea of this, you could look at issue #6.
With a tagging system, we could make the directory structure much simpler - mostly just grouping files in a way we might want to git-sub-modularize them in - and do the rest with tags like:

• licensing
• bom
• generated
• resource
• image
• video
• software
• hardware
• mechanical
• electrical
• source
• configuration
• firmware
• documentation
• manufacturing
• assembly
• user

Distribute modularity?

In unixish, currently all modules have to be a folder under the mod/ directory.
Instead of having it this way, we could remove that directory,
and instead mark a few other directories as modules, e.g. direct sub-dirs of src/mech/ and src/elec/.

Add `doc/design/` for design guidelines

@mikelovic

How to guide a non-(fully-)conforming projects maintainer to improve the situation?

It just dawned on me, that I did not think about this so far.

So we have a project, we compare it to all or one specific standard,
figuring out which directories and files are used as specified, and which not,
and then ... what?

We just tell the user to fix it, without giving any clues?
How could we give clues?

Ideas:

1. see if files/dirs outside of the standard are covered by an other standard,
   and then suggest a mapping (we do not yet have enough info for this in the spec, I think).
2. Just look at the file extensions, see if they appear somewhere in the spec, and suggest moving the files there.
3. see if directory names would be covered in an other location by the same spec, and suggest moving them there (could be multiple places!)
4. NOTE: Do not duplicate work done in other tools, like unwanted files (handled by osh-tool directly).