Skip to content

Contributors Guide

This guide describes how to contribute to the Digital Twin as a Service (DTaaS) project, from opening an issue to creating a pull request (PR), review and merge. Please read the Code of Conduct before contributing.

Project Goals

The DTaaS platform supports the creation, management and execution of Digital Twins (DTs) through a service-oriented architecture that promotes reuse of DT assets [1]. This documentation explains the software design and development processes of the project to members of the development team.

Additional resources:

Codebase Overview maps the directories of the monorepo.

Development Environment

The recommended development setup is the devcontainer defined in .devcontainer/devcontainer.json. It runs the containerised environment from developer/devenv/, which holds every toolchain needed to build and test the projects. Reopen in Container runs developer/devenv/init.sh on the host first. Outside VS Code, run that script once and follow developer/devenv/README.md.

Development Workflow

Contributors follow this procedure:

  1. Fork the main repository into a personal GitHub account.
  2. Configure Qlty, Codecov and SonarQube for the fork. Codecov does not need a secret token for public repositories.
  3. Use Node.js 26 and Python 3.14.
  4. Follow the Fork, Branch, PR workflow.
  5. Develop in the fork and open a PR from the working branch to the feature/distributed-demo branch of the fork. The PR triggers the GitHub Actions, Qlty, SonarQube and Codecov checks.
  6. Fix every issue the automated checks report.
  7. Once the checks pass, open a PR to the feature/distributed-demo branch of the upstream DTaaS repository.
  8. Project administrators or maintainers review and merge the PR.

Each PR should either satisfy a well-defined user story or improve code quality.

Local Testing lists the build and test commands to run before opening a PR.

Coding Agents and Editors

The project makes extensive use of coding agents. The primary usage scenarios include:

  • Co-development assistance
  • Code review support
  • Draft pull requests for prototyping ideas

Every coding agent reads the same instructions: AGENTS.md for the general coding guidelines and PROJECT.md for the repository-specific ones. Task-specific instructions are Agent Skills in .agents/skills/. Coding Agents describes these files and the available skills.

Contributors should disclose code generated by coding agents, particularly when such code embeds significant programming logic.

The following practices are strictly prohibited:

  • Contributing unknown or unreviewed code
  • Failing to understand the implications of generated code

Summary: Contributors must fully understand their contributions and should not delegate critical thinking to coding agents.

Code Quality

Code quality is checked by:

  • Static Analysis: Qlty reports linting issues. Install the Qlty CLI and run qlty check --no-fail --sample 5 --no-formatters to list them locally. Qlty analyses only the files that differ from the default branch (feature/distributed-demo).
  • Security Scans: SonarQube reports code quality and security issues.
  • Test Coverage: Codecov collects coverage reports.
  • Continuous Integration: every GitHub Actions workflow must pass.

Qlty

Qlty performs static analysis, linting and style checks.

New issues appear on the PR page. The issues and code sections of the Qlty dashboard list the rest.

Qlty Cloud skips pull requests opened from forks, because GitHub withholds its token from them. The Qlty workflow (.github/workflows/qlty.yml) runs the Qlty CLI on every pull request instead. It fails on new actionlint findings in changed workflows, and reports dependency advisories (osv-scanner) and code smells in the job log and summary without failing.

Contributions should not introduce new quality issues. Fix any that appear, using the suggestions from Qlty. Add an ignore flag only in exceptional cases.

Codecov

Codecov tracks test coverage for the whole project. The testing documentation describes the testing practices and workflows.

GitHub Actions

The project defines several GitHub Actions workflows. Every pull request and direct commit must pass all of them. Secrets for GitHub Actions lists the secrets and variables a fork needs for the publishing jobs.

References

[1] Talasila, Prasad, et al. "Composable digital twins on Digital Twin as a Service platform." Simulation 101.3 (2025): 287-311.