Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
78 lines (56 loc) · 3.16 KB

CONTRIBUTING.md

File metadata and controls

78 lines (56 loc) · 3.16 KB

Contributing

Thank you for your interest in contributing to the Digital Twins Definition Language (DTDL) Parser library. As an open source effort, we're excited to welcome feedback and contributions from the community.

Project Overview

This repository holds sources and resources for software artifacts related to parsing, validating, transforming, and inspecting models written in DTDL.

This repository does not accept changes to the language definition itself. It accepts changes to the codebase that are independent of the language, such as software architecture, documentation, and portions of the parser API.

Folder Structure

Top-Level Folders

The main top-level folders in the repository are as follows:

  • 📁 dtdl - Declarative definitions of the current and next versions of DTDL.
  • 📂 dotnet
    • 📁 gen - Source code of utilities that perform extraction, codegen, and analysis that produces other files and projects.
    • 📁 src - Source code (both handwritten and generated) of the parser and tools.
    • 📁 tests - Source code (both handwritten and generated) of tests that validate correctness of the parser and sub-components.
  • 📁 test-cases - Declarative tests cases for validating DTDL parsing.
  • 📂 tutorials - Markdown files illustrating use of the parser.
    • 📁 projects - C# project, source, and expectation files generated from the Markdown tutorials.
  • 📁 scripts - CMD files used by the Develop.sh script.

Generated (Read-Only) Code

The following folders contain generated files and inputs that feed into the production of generated files. PRs shall not include changes to files within:

  • 📁 dtdl
  • 📁 test-cases
  • 📁 pipelines
  • 📁 scripts
  • 📁 dotnet/gen
  • 📁 dotnet/src/DTDLParser/generated
  • 📁 dotnet/src/Remodel/generated
  • 📁 dotnet/tests/ParserUnitTest/generated
  • 📁 javascript/generated
  • 📁 images/generated
  • 📁 images/input/generated
  • 📁 tutorials/projects
  • 📁 api-docs

Building the Projects

The projects can be built with the following command:

dotnet build dotnet/DTDLParser.sln

Once built, the projects can be tested with the following commands:

dotnet test dotnet/tests/DtmiUnitTest 
dotnet test dotnet/tests/ResultFormatterUnitTest
dotnet test dotnet/tests/ParserUnitTest

Code Change Sequence

The following steps will be taken to submit changes to this repository:

  1. Create a fork of the repository.
  2. Modify code and/or other resource files.
  3. Execute the commands described above to build projects and execute tests.
  4. Create a PR back to this repository.
  5. Review pipelines failures and make appropriate changes.

Further Reading

For details on contributing to DTDL Parser development via changes to generation code, please refer to CONTRIBUTING.detailed