# Repository structure

The core and the plugins of Qualia and Qualia-CodeGen each have their own independent git repository,
with a number of files and directories at the root.
Each of them are described below, in alphabetical order with the directories first.

Except for specific requirements, it is recommended to avoid adding any stray files at the root of the repository.

## `conf/`

Optional, recommended for Qualia-Core and any Qualia-Plugin repository.

Contains example configuration files. For now, they are not included in the installed Python packages.

They are generally organized with a subdirectory for each dataset but this is not required.

Additionally, the `conf/tests/` directory is used to store functional test configurations.

For more information, see [ConfigurationFile](../UserGuide/ConfigurationFile)

## `docs/`

Mandatory for any Qualia-Core, Qualia-Plugin, Qualia-CodeGen-Core and Qualia-CodeGen-Plugin repository.

Contains the Sphinx-auto-generated documentation configuration as well as manually written documentation pages.

For more information, see <project:Documentation.md>.

## `src/`

Mandatory for any repository that contains source code.

The repositories are organized with the ["src layout"](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/),
meaning that the Python packages are under the `src/` directory at the root of the repository.

Each of the repository provides one top-level Python package.
This top-level Python package is what is installed with `pip install`, meaning that any resources,
including non-Python files, has to be placed inside the package in order to be included in the installation.
Non-Python files will generally be placed under the `assets/` subdirectory of the Python package.

For more information about the organization of Python packages, see <project:PackageStructure.md>.

C/C++ source code repositories also use a similar scheme where all the source code is stored under `src/`,
with a subdirectory for each library or executable whenever possible.

## `tests/`

Optional but higly recommended for any repository that contains source code.

Contains the automated tests (unit tests, functional tests, integration tests…).

For more information, see <project:Tests.md>.

## `third_party/`

Optional.

Contains git submodules.

## `.editorconfig`

Mandatory for any repository that contains source code.

Contains [EditorConfig](https://editorconfig.org/) settings to configure compatible editors with the most important style settings such as:
- `end_of_line`: should always be `lf`.
- `charset`: should always be `utf8`.
- `indent_style`: always `space` for Python files, generally `space` for C files and `tab` for C++ files.
- `indent_size`: always `4` for Python files, generally `2` for C files and `4` for C++ files.
- `max_line_length`: generally `131`.

## `.gitignore`

Optional but highly recommended.

Contains the list of files ignored by git.

Should be used to exclude any build product that can be re-generated, any log file, any user-defined configuration file, any temporary file.

For development branches, the `pdm.lock` file should be excluded as well.

## `.gitlab-ci.yml`

Mandatory for any repository that contains source code to run checks on, tests, documentation to generate…

The Gitlab CI/CD configuration file to run automatic tests, checks, generation, deployment, etc… when changes are pushed to the repository.

## `.gitmodules`

Optional.

The list of git submodules generated by git when a submodule is added.

## `CMakeLists.txt`

Optional but recommended for any repository containing C++ source code.

The CMake build system configuration used to build a C/C++ project.

## `LICENSE`

Mandatory.

Contains the license for the files in the repository.

By default, everything is proprietary and the license file should contain a `Copyright […]. All rights reserved.` statement.

When releasing open-source code, the appropriate open-source license should be inserted, such as AGPL-3.0 that was used for the public 1.0 release.

## `README.md`

Mandatory.

Contains the title, a short description, requirements and how to run the code in the repository if applicable.

## `pyproject.toml`

Mandatory for any repository containing Python source code.

Contains the metadata of the Python project, the dependencies, and the configuration for various development tools (test environment, linter, type checker…).