naming and location convention for metadata file

[moedn]

See details & my suggestions below ↓

File location convention:

• saving all files in the root level may create a mess
• saving files in the same level as the corresponding hardware design file may not be possible in all cases as repositories are sometimes a mess
• suggestion 1: saving all files in a "OKH" folder in the root level
• suggestion 2: squash everything into one huge TTL ← very hard to mantain for large assemblies, I guess
• suggestion 3: OSH-Module file is named "OSHM" and placed in the root folder; name the files however you like and store them wherever this fits your needs – as they are linked, this shouldn't affect anything
  • we suggest you name files after the type of the corresponding hardware position number in the BoM (e.g. POSH-MEC-5-1.TTL) and place them in the root folder of the corresponding (sub-)assembly or component

Naming convention:

• should be as easy & fast as possible; "okh-thingname.yml" as mandatory in OKHv1.0 isn't convenient in practice
• however, when saving all files in one root-level folder those files should carry some kind of human-readable identifier in their name
• copy of suggestion 3: OSH-Module file is named "OSHM" and placed in the root folder; name the files however you like and store them wherever this fits your needs – as they are linked, this shouldn't affect anything
  • we suggest you name files after the type of the corresponding hardware position number in the BoM (e.g. POSH-MEC-5-1.TTL) and place them in the root folder of the corresponding (sub-)assembly or component

[moedn]

Just had a quick great meeting with @hoijui – the following suggestion came up:

1. the file name must contain "OKH", this is sufficient for our crawler to identify it; however you may add whatever you like in this name (e.g. as suggested by OKH-thingname)
2. the file name must start with a dot "." → e.g. .okh.yml
3. the metadata file describing the whole module must be placed in the root directory; all metadata files for sub-modules or components may be placed in the corresponding folder so that they would be in the root directory if the module would be cloned into a individual repository; however as files are unambiguously referenced in the OSHM file, you can place them wherever you like

[hoijui]

yep, was a good talk! :-)
sleeping over it again, I would say the whole file-name should be fixed, not just contain "a tag".
that is, one fixed file in the root of each project (or module), and from there, you may reference other files with a freely choosable name. The first/main file in each folder should have this name if possible, even if it is not a project or module.

The reason for that -- which I did not think of yesterday during the talk -- is that some protocols (most notably HTTP) do not allow fetching a list of all names, but only to fetch a specific file. there are workarounds for that, like many web-servers serving HTML based/formatted file listings when you try to fetch a directory that has no index.html, but that you have to parse first, and it is not always on, and may only work if there is no index.html, ...

To have a fixed file name, is also how it is done everywhere else I can think of right now:

• .gitlab-ci.yml
• .travis-ci.yml
• .htaccess
• Makefile
• CMakeLists.txt
• .gitignore
• META-INF/MANIFEST.MF
• index.html

The later two are case-invariant, but I think they are only so because that was/is a windows bug aehh.. feature, which complicates things.

[moedn]

approved in today's meeting