udmi

UDMI / Docs / Guides / Development

Development

Schema Documentation

The schema documentation in gencode/docs must be kept up to date with any changes to the schema. Any additions to the schema should also include annotations to describe the new elements. The updated documentation is generated by running the script bin/gendocs and its output committed to the repository with the changes. Required python dependencies are in etc/requirements.txt which must be installed for the script to run.

Troubleshooting

If documentation CI tests are failing, check the basic system requirements - python modules installed and matching versions in etc/requirements.txt, and GNU variants sed and find. An unsupported system will generate documentation with changes, even when the underlying schema has not changed. gendocs works best under Linux.

New schema files should automatically receive an entry in the index gencode/docs/readme.md file if they are not referenced by any other schema file. If a schema file is referenced by another schema file, but should still have an entry in the index page, then the name should be added to the to the ALWAYS_ROOT list in bin/gencode_root_schemas.

Entries in the index gencode/docs/readme.md page sectioned according to the value of $section in the schema file. The section must also exist in the template etc/schema_readme_template.md, and must match (case sensitive) the value of $section, otherwise the schema entry is inserted under the Other section

Releases

The bin/upgrade_version tool updates :

• the $udmi_version field in schema files,
• the version in version in tests/**/*.json according to manually curated file
• documentation inline message examples.
• the UDMI_VERSION constant in specific JAVA files.

File in the tests directory must be listed in etc/upversion.txt. Only files which are preceded by a y in upversion.txt will have their version upgraded. Comments are supported after the file path, e.g. y tests/schemas/state/makemodel_upgrade.json tests message upgrade from v1

bin/upgrade_version carries out several checks on files which must be cleared before an update.

bin/upgrade_version does not update any generated files (e.g. for CI testing, refer to below list.)

An entry for the new version must be added manually in common/src/main/java/com/google/udmi/util/SchemaVersion.java

The entry in validator/src/main/java/com/google/daq/mqtt/util/ConfigUtil.java must be updated.

The below files need to be updated. Do not blindly copy! Inspect all diffs and confirm they are expected

• After bin/test_trace simple, contents of sites/udmi_site_model/sites/out into tests/traces/simple/expected
• After bin/test_validator, /tmp/validator.out into /etc/validator.out (reset any changes to sites/udmi_site_model first and and run bin/registrar)
• After bin/test_registrar && bin/test_sites, the out directory for each device in tests/downgrade.site/devices/ into the expected subdirectory (note these files are ignored by git, but must still be committed)

Useful commands

• rm -rf tests/sites/*/**/*/out && rm -rf tests/sites/*/out to remove out files from bin/test_registrar

The workflow can be tested with an empty commit (git commit --allow-empty -m "Blank commit to trigger CI"; git push). On an unmodified branch, these tests should pass if correctly configured

This site is open source. Improve this page.