Contributing to USDRT

Clone It!

Clone this repository directly from Gitlab.

Create a branch to begin work, using the convention

dev/JIRA_or_feature_or_bug_name

For example:

dev/OM-98546
dev/scenegraph_open_crash
dev/add_delegate_PI_support

Work that will shared for discussion and CI/CD but is not intended for merging should use this naming convention:

draft/JIRA_or_feature_name

For personal development and non-public testing, please use this branch naming convention:

personal/username/feature_or_test_or_whatever

… or use a Gitlab fork and push branches to your fork for backup and sharing.

draft/ and personal/ branches are subject to periodic cleanup and should be pushed to a Gitlab fork if you need them to persist for more than a month.

Build it!

USDRT uses repo_build to manage the build code for the repository. You can start the process using one of the platform-specific build scripts:

./build.bat

To build only for debug or release:

./build.bat -d
./build.bat -r

To clean your build:

./build.bat -c

To generate project files only without building:

./build.bat -g

Branches

Development for bugfixes and new features should be based off of the “develop” branch, and target the “develop” branch for MRs.

“develop” is merged into “deploy” for release, which is triggered automatically on TeamCity and will create a new packman package.

Releases from “deploy” will be tagged with the relevant version number for that release.

Hotfix branches will be created from the deploy branch as necessary in order to support hotfixes for rapid deployment. The hotfix branch reflects the release version in its branch name, ex: hotfix/1.5.2, and ‘hotfix’ will be reflected in the packman package name as well. Hotfix branches are not meant for long-term consumption and consumers should move back to a standard release package as soon as the deadline / demo / whatever emergency is complete.

Support branches

In order to support deployed Kit versions, branches will be periodically created that align with a specific Kit release. Two branches will be created per Kit version that mirror the develop/deploy paradigm. A version-specific develop branch named like “support_104_develop” will be used to accumulate changes, either cherry-picked from the develop branch or branched directly for version-specific changes. That develop branch will be merged into the version-specific deploy branch named like “support_104_deploy” to release a new USDRT build.

Merge requests

Merge requests should generally target the “develop” branch.

Before creating a merge request for merge consideration, please squash your commits down to the fewest logical commits that represent the purpose of each code change. (Squashing is not necessary for Draft MRs). Additionally, your changes should be rebased onto the latest commit in the “develop” branch as of the time you create the MR.

Your code should pass all tests before creating the MR. You can run tests with this command:

./repo.bat test

If you have not run code formatting, this should be done and added as a seperate commit before creating the MR:

./repo.bat format

If your code formatting is incorrect, a Gitlab pipeline will fail and block your MR from merging.

And finally, your change should not cause documentation generation to fail:

./repo.bat docs

If the repo_docs command succeeds, you’re ready to file an MR.

A TeamCity job is triggered for all MRs: https://teamcity.nvidia.com/project.html?projectId=Omniverse_Libraries_UsdRt&branch_Omniverse_Libraries_UsdRt_Develop=%3Cdefault%3E

If your MR fails to build on all platforms, or causes unit tests to fail, the MR will be blocked by an external TC step in the Gitlab pipeline until the problem is resovled.

Once your MR is approved and all pipelines are passing, you can merge it at your convenience.

Code standards

For C++, please follow the Carbonite Style Guide with the following exceptions:

• The public USDRT Scenegraph API (once developed) will the USD coding conventions in order to facilitate a drop-in replacement API for USD

C++ libraries should be created in the usdrt namespace.

For Python, please follow PEP8 with the following exceptions:

• Max line length of 120

• Use Google-style docstrings

• The public USDRT API (once developed) will follow the USD coding conventions, which don’t match PEP8 in the slightest

Python libraries should be created in the usdrt Python package.

Code formatting is checked / updated by clang-format and black. After you have committed your code, please run a formatting pass and commit any changes:

./repo.bat format

Or just test if your formatting is correct:

./repo.bat format -v

The GitLab pipeline that runs on your MR will fail if formatting is not correct.

Documentation

USDRT uses repo_docs to generate documentation, and repo_docs uses Doxygen and Sphynx to build that documentation. Documentation is build automatically as part of the TeamCity build process, and you can also generate it locally:

./repo.bat docs

This command should succeed without error. If an error occurs while building documentation, please fix it before checking in your changes.

Documentation is output to _build/docs/usdrt/latest

We try to follow the Omniverse Documentation Guidelines. There are also guides for writing C++ documentation for Doxygen and writing reStructured Text for project documentation.

USDRT is configured to build public and internal documentation. By default, repo_docs will build both, but you can specify one or the other with the -b flag:

./repo.bat docs -b public
./repo.bat docs -b internal

Public docs are published to AWS and are world-readable. Internal docs are published on GitLab Pages and only visible to NVIDIA developers.

If you run into trouble building docs, you can debug with repo_docs logger:

export OMNI_REPO_MAN_LOG_LEVEL=debug

Testing

USDRT uses repo_test to run suites of unit tests. There are currently two tests suites configured - one for C++ code that uses the doctest framework, and one for Python code that uses the Python unittest package. You can run these test with the following commands:

./repo.bat test -s cpp

./repo.bat test -s python

The C++ suite is run by default if you don’t provide a suite argument. You can also select develop or release builds with the -c flag:

./repo.bat test -s cpp -c release

The release build is run by default if a config argument is not provided.

Any new code added to the usdrt repo should include a new test to validate the code, where possible. Any bugs that are fixed in the usdrt repo should include a test that validates the fix and will catch regressions of the bug should they occur later.

To speed up testing iterations, you can run specific C++ test sets using the -e flag to pass through arguments to test.unit. For example, to run only the Scenegraph API tests, you could do:

./repo.bat test -e="-tc=*scenegraph*"

Licensing

All third party code and libraries must be approved by SWIPAT and fetched from packman. There should be no third party code used directly in this codebase. To add a new library after SWIPAT approval, follow the Carbonite packaging guidelines. New libraries should be added to omniverse/externals for SWIPAT tracking and packaging purposes - see here for a guide on how to do this. Please read Packman Package Licensing and Omniverse OSS License Compliance for more details.

To update licensing files after adding a new dependency:

./repo.bat licensing gather -d . -p deps/target-deps.packman.xml deps/host-deps.packman.xml deps/usd-deps.packman.xml --platform windows-x86_64