Welcome to the Digital Twin as a Service (DTaaS) contributing guide
Thank you for investing your time in contributing to our project!
Read our Code of Conduct to keep our community approachable and respectable.
In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.
It helps development team members get familiar with the DTaaS project software design, and development processes. Please see developer-specific Slides, Video, and Research paper.
Please use the steps given here to have suitable development environment.
There is a devcontainer configuration for the project. Please use it to get a dockerized development environment. DevContainer is the easiest way to get started.
The code base has been developed for most part on Ubuntu/Linux Operating System.Thus certain parts of the code base might have bugs when run on Windows. At the moment, only runner has problems running on non-Linux OS.
The development environment can be installed by using the following scripts.
bash script/env.sh
bash script/docker.sh
The development environment scripts for Windows are still buggy. Any help in improving them is greatly appreciated. Given that, caveat, please use the following installation steps for Windows.
Two powershell installation scripts, namely base.ps1
and env.ps1
are available to install the required
software packages. But errors might crop up due to missing
environment variables. The potential errors are:
npm is not recognized.........
inbase.ps1
.gem is not recognized.........
inenv.ps1
If you encounter these errors,
remember to include node and ruby installation locations in
PATH environment variable
(Settings --> search for "system environment variables"
--> Advanced --> Environment Variables --> PATH
).
The base.ps1
and env.ps1
scripts can be run again after setting
the correct PATH environment variable.
Another way to solve the PATH environment problem is to install Nodejs and Ruby software packages before running the powershell scripts.
- Install the latest stable version of NodeJS from the official NodeJS website.
- Install Ruby from official Ruby website and follow all the defaults during the installation.
Then, open powershell with administrative priviledges and run the following commands in the given order:
powershell -F script/base.ps1
powershell -F script/env.ps1
powershell -F script/docker.ps1
To manage collaboration by multiple developers on the software, a development workflow is in place. Each developer should follow these steps:
- Fork of the main repository into your github account.
- Setup Code Climate and Codecov for your fork. The codecov does not require secret token for public repositories.
- Install git-hooks for the project.
- Use Fork, Branch, PR workflow.
- Work in your fork and open a PR from your working
branch to your
feature/distributed-demo
branch. The PR will run all the github actions, code climate and codecov checks. - Resolve all the issues identified in the previous step.
- Once changes are verified, a PR should be made to
the
feature/distributed-demo
branch of the upstream DTaaS repository. - The PR will be merged after checks by either the project administrators or the maintainers.
Remember that every PR should be meaningful and satisfies a well-defined user story or improve the code quality.
The project code qualities are measured based on:
- Linting issues identified by Code Climate
- Test coverage report collected by Codecov
- Successful github actions
Code Climate performs static analysis, linting and style checks. Quality checks are performed by codeclimate are to ensure the best possible quality of code to add to our project.
While any new issues introduced in your code would be shown in the PR page itself, to address any specific issue, you can visit the issues or code section of the codeclimate page.
It is highly recommended that any code you add does not introduce new quality issues. If they are introduced, they should be fixed immediately using the appropriate suggestions from Code Climate, or in worst case, adding a ignore flag (To be used with caution).
Codecov keeps track of the test coverage for the entire project. For information about testing and workflow related to that, please see the testing page.
The project has multiple github actions defined. All PRs and direct code commits must have successful status on github actions.