Versioning and documentation: Quick Reference — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)

Versioning and Documentation Quick Reference for OpenUSD Pipeline Development

This quick reference provides essential facts, definitions, and best practices for versioning and documentation within OpenUSD pipeline development, a critical component of the NVIDIA-Certified Professional: OpenUSD Development certification.

Versioning

• Purpose: Track changes to USD assets and pipeline components to ensure reproducibility, collaboration, and rollback capability.
• Types of Versioning: Asset versioning (individual USD files or collections) and pipeline configuration versioning (scripts, exporter hooks, build files).
• Version Control Systems (VCS): Use Git or Perforce for managing USD assets and pipeline code. Perforce is common in production pipelines for large binary assets.
• Semantic Versioning: Adopt semantic versioning (MAJOR.MINOR.PATCH) for USD assets to indicate backward compatibility and changes:
• MAJOR: incompatible API or schema changes
• MINOR: backward-compatible feature additions
• PATCH: backward-compatible bug fixes
• Branching Strategies: Use feature branches for experimental changes; maintain stable branches for production-ready assets.
• Tagging: Tag releases in the VCS to mark stable asset versions for pipeline consumption.
• Locking and Checkout: For binary USD assets, implement file locking to prevent concurrent conflicting edits.

Documentation

• Scope: Document asset metadata, version history, pipeline build configurations, exporter hooks, and flattening procedures.
• Formats: Use Markdown or reStructuredText for human-readable docs; embed metadata in USD files using customData dictionaries.
• Asset Metadata: Include creator, creation date, version number, dependencies, and usage notes within USD metadata.
• Pipeline Documentation: Maintain clear instructions for build configuration, exporter hook usage, and flattening processes.
• Change Logs: Maintain a changelog file summarizing modifications per version for quick reference.
• Automation: Integrate documentation generation into CI/CD pipelines to keep docs up to date with code and asset changes.
• Accessibility: Store documentation in centralized, searchable repositories accessible to all pipeline users.

Best Practices Summary

• Consistently apply semantic versioning to all USD assets and pipeline components.
• Use a robust VCS with branching, tagging, and locking to manage asset and pipeline changes.
• Embed essential metadata directly in USD files to improve traceability.
• Keep documentation concise, up to date, and integrated with pipeline workflows.
• Automate version and documentation updates where possible to reduce human error.

Remember: Effective versioning and documentation are foundational to maintaining a reliable, scalable OpenUSD pipeline that supports collaboration and asset integrity.

More in this topic

Exporter hooks and build configuration — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Versioning and documentation: Practice Questions — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Versioning and documentation — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Pipeline design and asset management: Quick Reference — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Pipeline design and asset management: Common Mistakes — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Flattening assets — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Pipeline design and asset management — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Pipeline design and asset management: Worked Example — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Pipeline Development — NVIDIA-Certified Professional: OpenUSD DevelopmentVersioning and documentation: Common Mistakes — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Versioning and documentation: Worked Example — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)Pipeline design and asset management: Practice Questions — Pipeline Development (NVIDIA-Certified Professional: OpenUSD Development)