Build and Developer Experience Issues

[philsawicki]

Introduction

While attempting to contribute tests and automation to the glTF plugin included to this repository, participants of Khronos' 3D Formats Tooling TSG expressed facing challenges in configuring and building the sources offered here. This issue collects the feedback expressed by members of the group, in the hope of facilitating onboarding and promoting contributions to this project – for which members are grateful.

Context

The 3D Formats Tooling TSG operated by Khronos was hoping to compile a list of features supported for interoperability between glTF and OpenUSD, through an accurate gap analysis and accompanying test suites against the glTF Sample Assets. The information collected by performing this exercise would have contributed knowledge to the general community about the breadth and stability of the interoperability features, and opened the door to contributions for features that may have been identified as desirable, if missing.

Although described in the project's README files, the instructions for configuring a build environment and configuring a build for producing the glTF File Format plugin for OpenUSD appeared to be more intricate than expected for the majority of potential contributors not yet familiar with OpenUSD.

This initial high barrier to entry may inadvertently cause individuals who would have been keen on contributing their expertise to the OpenUSD File Formats in this repository to invest their time in other projects where they perceive being more impactful, preventing them from further developing and supporting the valuable resources Adobe shares here.

Current Behavior

In attempting to set up their environments for contributing to the projects, members have noted that although build instructions are present in the repository's README file, they can appear challenging to potential contributors not fully versed in OpenUSD. Feedback from some include:

• As of this writing, build artifacts for the plugins are not available through PIP packages or GitHub Releases. This currently requires contributors to build from sources, with build instructions hinting at building the all File Format plugins present in this repository when only a subset may be desired.
  • e.g. Contributing only to the glTF File Format plugin may require fewer dependencies and options than otherwise required to produce artifacts for all plugins.
• Alignment and compatibility with OpenUSD releases is currently offered through badges at the top of README files. Contributors may wish to have more prominent access to information related to Long-Term Support of release cadence for newer versions of OpenUSD.

Key Desired Abilities

In attempting to contribute to this project, Khronos members noted they were looking to perform validation tests for glTF assets referenced within OpenUSD Stages, and faced challenges in attempting to accomplish this. In particular, they noted they were seeking to perform the following actions on this repository:

1. Download prebuilt artifacts, in order to install via PIP the OpenUSD File Format plugins compatible with the official usd-core package. Including:
   1. Build artifacts compatible with platforms officially supported by OpenUSD (i.e. Windows, Linux, MacOS).
   2. (Optionally) Build artifacts available alongside the repository's GitHub Releases.
2. Access developer documentation, which:
   1. Indicates the compatibility between File Format plugins and the corresponding OpenUSD release(s).
   2. States the minimal required steps to build File Format plugins (in particular, the glTF File Format plugin).
   3. Speaks to the intended to the Long-Term Support (LTS) of offered File Format plugins vis-à-vis their corresponding OpenUSD versions.

Note: Some participants expressed facing challenges when attempting to set up their environments for contribution due to File Format plugins as they were not aware of the required corresponding OpenUSD versions. Today, this information is only present through badges at the top of README files, which indicate File Format plugins are built via automation for OpenUSD 24.05 while Pixar offers 24.08 by default (with 24.11 releasing in the near future).

References

• usd-core PIP package

[kwblackstone]

Thank you for your detailed feedback and for the effort your team at Khronos has put into exploring the File Format plugins. We understand the importance of minimizing barriers for new contributors and making interoperability between glTF, along with many other formats, with USD as accessible as possible.

Our team is aware of the areas you highlighted, particularly around simplifying the build process and further enhancing testing infrastructure. We have heard feedback around providing a PIP package or artifact that is easier to install. Pip packages don't appear to be the optimal solution as these plugins are not python modules. A GitHub Release could be feasible in the future, although current build complexities make it difficult to release a packaged USD build, its dependencies, and the fileformat plugins, that will work out of the box across different user environments.

Thank you as well for the documentation feedback, we will look to make the USD versioning more prominent and want to start investigating a good way to communicate the roadmap for these plugins. In the meantime, if there are specific blockers or questions where we can assist, please let us know. Your input is valuable to us, and we appreciate your patience as we continue enhancing these plugins.

[philsawicki]

Thank you for the note @kwblackstone. I appreciate the perspective you provided 👍