Validation Pipeline

Validation Pipeline

Discussion https://github.com/Azure/iot-plugandplay-models-tools/issues/6

Upon issuing a pull request, a user can expect that the following validations will be executed.

PR Validation checks

Order to be determined

• The @id property of the root element will be inspected.
  • If the value isn't a valid user-generated DTMI, the request will fail.
• The @id property of the root element will be compared to the file path, as defined in https://github.com/Azure/iot-plugandplay-models-tools/wiki/Resolution-Convention#folder-and-file-structure
  • This MUST match the file name or the request will fail.

  Example: a file defining dtmi:com:Example:Person;1 would be required to be in a file in ./dtmi/com/example/person-1.json. Similarly, a file defining dtmi:COM:ExAmPlE:PeRsOn;1 would be required to be in the file ./dtmi/com/example/person-1.json. This means that even though the DTMI are case-sensitive, the file structure holding the files is not. Additional information on the case sensitivity can be found in Resolution Convention

• Any specified @id on sub elements will be checked to see if it resembles a DTMI. If not, it will be ignored, as described in https://github.com/Azure/iot-plugandplay-models-tools/wiki/Resolution-Convention#unique-id-elements
  • If so, the DTMI MUST follow a namespace scoping.

  Example: a file specifying dtmi:com:example:person;1 can have a schema defined for dtmi:com:example:person:phoneNumber;1 but cannot have a schema defined for dtmi:com:telephone:number;1

• The DTDL parser will run against each if the submitted file(s) and ensure they will parse independently.
  • Failure to parse will fail the request.
  • The validation PR will take a dependency on a parser LTS version (TBD)
• Attempts will be made to scan for secrets and inappropriate content using existing tooling.
  • Any secrets of content items will be marked as warnings instead of errors.
• The default branch will include branch security and ./CODEOWNERS file to alert any code owners that have been previously configured
• No deletions, updates or renames are allowed.
  • Will generate warnings as these could be major breaking changes to devices using them in production.
  • Check the DTMI with a list of reserved words (eg, azure) and produce warning if found

Expected validation issues

checks may run in parallel; order not guaranteed

• Invalid DTMI (see above)
• Invalid path structure (see above)
• Invalid sub DTMI (see above)
• Invalid JSON. JSON document does not parse using standard language tools
• Invalid DTDL. Document does not parse using the DTDL parser utility.
• Reserved word found in root ID

Manual approvals

Manual Approvals Playbook

1. Ensure that a code owner (if any has been configured) has approved the request
2. Ensure that the validation has completed without errors.
3. Investigate any warnings (content/secrets)
4. Always SQUASH commits.
5. Ensure no deletions, updates or renames exist without extenuating circumstances.
   • Changes to models that are in use are to be considered HUGE breaking changes.

Reviewing SLA

• Manual inspection of the PR will be guaranteed in 3 business days.
• Raise an issue on the repository using the (template name to be determined) issue template.

Branch Protection Rules

The following branch protection rules will be applied and enforced.