Consider revising naming of top-level folders

[glopesdev]

• Proposed
• Prototype: Not Started
• Implementation: Not Started
• Specification: Not Started

Summary

With the upcoming application of bonsai-rx/prefect to the repositories in harp-tech, we have one opportunity to revise the structure of the repository. This proposal is to align the folder structure with common patterns in .NET and bonsai-rx repos.

By clarifying the situation with licensing and making the structure more digestible, we would be encouraging others to follow a clear recommendation on how to manage the creation process of open-source Harp devices with multiple component parts.

Motivation

This would make it easier for other developers and contributors to understand the structure of the repositories, ease the maintenance burden, and unify repositories across harp-tech. We also need to introduce new folders for device documentation, and it would help to decide the naming of those as well.

Detailed Design

Proposed new repository structure:

📦device.name
 ┣ 📂.bonsai
 ┣ 📂.github
 ┣ 📂build
 ┣ 📂docs
 ┃ ┣ 📂articles
 ┃ ┣ 📂images
 ┃ ┣ 📂workflows
 ┃ ┣ 📜docfx.json
 ┃ ┗ 📜LICENSE
 ┣ 📂generators
 ┣ 📂licenses
 ┣ 📂src
 ┃ ┣ 📂api
 ┃ ┃ ┗ 📜LICENSE
 ┃ ┣ 📂app
 ┃ ┃ ┗ 📜LICENSE
 ┃ ┣ 📂firmware
 ┃ ┃ ┗ 📜LICENSE
 ┃ ┗ 📂hardware
 ┃ ┃ ┗ 📜LICENSE
 ┣ 📜.editorconfig
 ┣ 📜.gitignore
 ┣ 📜device.yml
 ┣ 📜Directory.Build.props
 ┣ 📜LICENSE
 ┗ 📜README.md

REUSE Specification FAQ

To clarify license provenance, the root LICENSE file should clarify project licensing terms, similar to the Linux kernel and using SPDX identifiers whenever possible.

For example:

LICENSE

The contents of the Harp Device repository are licensed SEPARATELY under the licenses indicated below:

  - App: MIT
  - Documentation: CC-BY-SA-4.0
  - Hardware/PCB: TAPR-OHL-1.0
  - Hardware/Mechanical: CC-BY-SA-4.0
  - Firmware: MIT
  - Interface: MIT

All contributions to the Harp Device repository are subject to the terms in this LICENSE file.

Drawbacks

Renaming the top-level directory structure, even if done automatically, would create a burden to validate correctness in all repositories.

Alternatives

It is currently very hard to understand the licensing situation with harp-tech devices, which can discourage people from using, modifying or contributing to existing devices, and makes it harder for them to adopt similar structures for their projects.

There is also no agreed upon convention for a per-project documentation folder. To keep with the current structure we could attempt also the following:

📦device.name
 ┣ 📂.bonsai
 ┣ 📂.github
 ┣ 📂App
 ┃ ┗ 📜LICENSE
 ┣ 📂Documentation
 ┃ ┣ 📂articles
 ┃ ┣ 📂images
 ┃ ┣ 📂workflows
 ┃ ┣ 📜docfx.json
 ┃ ┗ 📜LICENSE
 ┣ 📂Firmware
 ┃ ┗ 📜LICENSE
 ┣ 📂Generators
 ┣ 📂Hardware
 ┃ ┗ 📜LICENSE
 ┣ 📂Interface
 ┃ ┗ 📜LICENSE
 ┣ 📜.editorconfig
 ┣ 📜.gitignore
 ┣ 📜device.yml
 ┣ 📜LICENSE
 ┗ 📜README.md

Unresolved Questions

Design Meetings

[bruno-f-cruz]

If the recent proposal (harp-tech/reflex-generator#86) to include a python api with the automatic code generation, we should specify how this artifact is expected to be represented in this proposed structure.

Additionally, from previous meetings and conversations, we should also consider discussing how to account for:

• Examples - This could probably be moved to the documentation
• Tests - Not sure what to do here. These will likely be device-specific but also interface-specific.