Repository Structure
Our repositories follow a common structure, in terms of folders and files to include. We distinguish between three kinds of projects:
- Hardware Projects: Those that define a physical thing, such as a power supply module or motor drive module. Typically they also include some embedded software, referred to as firmware.
- Software Library: These are software packages that can be used in higher level software, for example in firmware or software applications. In Python, you would install such via the pip package manager.
- Software Applications: Self-standing, larger applications that users can install, configure, and operate. They usually have a specific purpose, for example a simulator or a mission control system.
Naming Convention
For hardware projects and software applications which will be published in the "Elements" category, the naming starts with LC, followed by a four digit number from the numbering scheme of the reference architecture.
For software library projects, the naming is: "programming_language"-"library_name". For example: "rust-spacecan".
Versioning
Hardware projects have only main version numbers. For example, starting with prototype v0, then first release v1 and so on.
Software applications and library projects follow the Semantic Versioning specification. For example, v2.3.1 for 2nd main release, with 3rd minor release, with first patch.
Readme File
Every project must contain a README.md landing page. The structure of this markdown file should follow closely this structure:
# <Project Name>, Version <version-number>
// Write here a paragraph or two for an overview on what this project is about.
 // Insert a picture (640 pixels width) of the project.
## Getting Started
// Write here how to build and operate the project. For example:
See the [Assembly Guide](docs/assembly/index.md) and to the [Configuration Guide](docs/configuration/index.md) for setting up the system. For operation, refer to the [Operation Guide](docs/operation/index.md).
## License
The <license-name> license applies. See the [LICENSE](./LICENSE.txt) file for details.
## Contact
Visit the LibreCube website (https://librecube.org/) or send us an email (info@librecube.org).
Reference Folder Structure
Find here the reference folder structure for the different project categories. You may add and omit folders as reasonable for your project.
Hardware Projects
| Folder/File | Description |
|---|---|
| build/ | Contains a bom.csv (bill of materials) and the artifacts for production, organized in subfolders by type (gerber, stl, etc.). |
| docs/assembly/index.md | Documentation for the assembly of the component. |
| docs/configuration/index.md | Documentation on how to configure the component, such as calibrations and settings. |
| docs/operation/index.md | Documentation on how to operate the component, including examples. |
| src/mechanical | Contains all the mechanical source files (mostly FreeCAD). |
| src/electrical | Contains all the electrical source files (mostly KiCAD). |
| src/firmware | Contains the code for the microcontroller (mostly MicroPython or Rust). |
| tests/ | Documentation and records of any testing done with the component. |
| .gitignore | Lists the files to exclude from git version control. Generate it here. |
| CONTRIBUTORS.txt | Lists the contributors to this project, with name and email. |
| LICENSE.txt | Contains the chosen license for this project. See license section. |
| README.md | The landing page readme. |
| picture.png | A nice picture (640 pixels width) of this project. |
Software Applications
| Folder/File | Description |
|---|---|
| build/ | The (runnable) artifacts that are compiled or generated from the source code. |
| docker/ | Optionally, a docker container that contains the software application. |
| docs/installation/index.md | Documentation for the installation of the software application. |
| docs/operation/index.md | Documentation on how to operate the software application, including examples. |
| src/ | Contains all the software source files. Structured as how the programming language requires it. |
| tests/ | Unit and higher level tests that will be run from the continuous integration (CI) script. |
| .gitignore | Lists the files to exclude from git version control. Generate it here. |
| .gitlab-ci.yml | The continuous integration (CI) script that runs for new commits to ensure code quality. |
| CONTRIBUTORS.txt | Lists the contributors to this project, with name and email. |
| LICENSE.txt | Contains the chosen license for this project. See license section. |
| README.md | The landing page readme. |
| picture.png | A nice picture (640 pixels width) of this project. |
Software Library Projects
| Folder/File | Description |
|---|---|
| docs/index.md | Documentation on how to use the module and API specification (api.md). |
| examples/ | Provide some easy to understand examples on how to use that module. |
| src/ | Contains all the software source files. Structured as how the programming language requires it. |
| tests/ | Unit (and possibly higher level) tests that will be run from the continuous integration (CI) script. |
| .gitignore | Lists the files to exclude from git version control. Generate it here. |
| .gitlab-ci.yml | The continuous integration (CI) script that runs for new commits to ensure code quality. |
| CONTRIBUTORS.txt | Lists the contributors to this project, with name and email. |
| LICENSE.txt | Contains the chosen license for this project. See license section. |
| README.md | The landing page readme. |
| picture.png | A nice picture (640 pixels width) of this project. |
| further files... | One or more other files required for installation. For example a pyproject.toml file. |