Skip to content

Contributors Guide

This guide provides an overview of the contribution workflow for the Digital Twin as a Service (DTaaS) project. Contributors are encouraged to review the Code of Conduct to ensure a respectful and collaborative community environment.

The following sections outline the contribution process, from opening an issue to creating a pull request (PR), conducting reviews, and merging the PR.

Project Goals

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

Additional resources include:

💻 Development Environment

A devcontainer configuration is provided in .devcontainer/devcontainer.json for the project. This configuration offers a dockerized development environment and represents the recommended approach for establishing a consistent development setup. DevContainer provides the most straightforward method for initializing the development environment.

🏗 Development Workflow

A structured development workflow is employed to manage collaboration among multiple developers. Each contributor should adhere to the following procedure:

  1. Create a fork of the main repository into a personal GitHub account.
  2. Configure Qlty, Codecov, and SonarQube for the forked repository. Note that Codecov does not require a secret token for public repositories.
  3. Utilize Node.js 24 and Python 3.12 development environments.
  4. Follow the Fork, Branch, PR workflow methodology.
  5. Develop within the fork and create a PR from the working branch to the feature/distributed-demo branch. The PR triggers all GitHub Actions, Qlty, SonarQube, and Codecov checks.
  6. Address all issues identified during the automated checks.
  7. Upon successful verification, submit a PR to the feature/distributed-demo branch of the upstream DTaaS repository.
  8. The PR undergoes review and is merged by either project administrators or maintainers.

Each PR should represent a meaningful contribution that satisfies either a well-defined user story or improves code quality.

✨ 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

This project is structured as a monorepo and includes copilot instructions that inform GitHub Copilot about the project structure and software development conventions.

Modern Code IDEs such as VS Code and Cursor provide native integration with coding agents, requiring no additional configuration for LLM-driven development workflows. 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

Project code quality is assessed through the following mechanisms:

  • Static Analysis: Linting issues are identified by Qlty. Installation of Qlty CLI is recommended. Execute the command qlty check --no-fail --sample 5 --no-formatters to identify code quality issues. Note that Qlty only analyzes files that differ from the default branch (feature/distributed-demo).
  • Security Scans: Code quality and security issues are identified by SonarQube.
  • Test Coverage: Coverage reports are collected by Codecov.
  • Continuous Integration: All GitHub Actions must complete successfully.

Qlty

Qlty performs static analysis, linting, and style checks to ensure optimal code quality for project contributions.

While newly introduced issues appear directly on the PR page, specific issues can be addressed by visiting the issues or code section of the Qlty dashboard.

Code contributions should not introduce new quality issues. If such issues arise, they should be resolved immediately using the appropriate suggestions from Qlty. In exceptional cases, an ignore flag may be added, though this approach should be employed sparingly.

Codecov

Codecov maintains test coverage metrics for the entire project. For detailed information about testing practices and workflows, refer to the testing documentation.

GitHub Actions

The project defines multiple GitHub Actions. All pull requests and direct commits must achieve successful status on all GitHub Actions.

References

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