Contributing to Carbonite¶
Carbonite is the lowest layer of Omniverse. It’s an attractive place to check in code, since said code’s reach will be broad. While good code accepted to Carbonite will result in increased productivity, bad code will be disastrous to the Omniverse ecosystem. As such, code submitted to Carbonite is put under a great deal of scrutiny.
When submitting code to Carbonite, expect the following:
Bug fixes, documentation, and tests are greatly appreciated.
New features are welcome, but please reach out to us before embarking on new features. As a team, we’re priority driven. We focus on Omniverse’s top needs and actively seek to not be distracted by features not on the roadmap.
If your contribution is a new feature, we’ll question if it belongs in the Carbonite SDK or somewhere else in Omniverse. We focus on providing an SDK that consists of foundational components. Often we find contributions are better suited in another, “higher-level”, Omniverse SDK.
Overview documentation is a must. We love API documentation, but find “overview” documentation more valuable. Fundamentally, we want you to describe the problem you’re trying to solve, how your component solves it, and how customers can get the most out of your contribution. See Omniverse Documentation Guidelines for details.
API documentation is a must. We ship an SDK, and SDK’s are all about APIs. The public surface of your API must be documented. See Omniverse Documentation Guidelines for details.
All code is tested. We don’t expect 100% test coverage (that’s a plus), but we do expect test coverage over both expected and erroneous usage of the submitted APIs. We expect contributors to write tests not for themselves, but for future contributors extending the functionality of the original system. When writing a test, think: “What are the things that are important to this interface? What are future maintainers likely to break?” See Testing for more information.
To summarize, your contribution must:
Be foundational to Omniverse
Be documented so developers can use it
Be tested so future contributors can make it better
If your contribution doesn’t meet the criteria above, don’t fret. Reach out to us and we’ll help you find the right place in the Omniverse for your contribution.
The Contribution Process¶
Contributing to Carbonite can be broken up into the following steps:
Fork the Carbonite repository. Details can be found at Forking Carbonite.
Clone your fork. See Cloning Carbonite.
File a Jira issue for visibility. See How to File a Carbonite Issue.
Create a feature branch.
Hack / Test / Document
Commit / Push your changes to your fork
Submit Merge Request (MR)
Address feedback
Merge your changes to the Carbonite repository
Publish a new Carbonite package
Creating a Feature Branch¶
After forking and cloning, create a branch in your fork. Assuming your username is “ncournia” and your adding a documentation fix to the omni.bind tool:
git fetch origin
git create origin/master -b feature/ncournia/omni.bind-doc-fix
The branch naming scheme above isn’t required, it’s just a convention.
If you’re new to git, now is a great time to get familiar with its basics.
Hacking / Testing / Documenting¶
You’ll next want to build Carbonite. A full guide can be found at Building Carbonite.
And then comes the hacking. That’s the fun part. See our development guide for how to add new projects to the build system and recommendations on workflow.
Or maybe you write your tests first? Or after? It doesn’t matter to us. A guide to writing and running Carbonite tests can be found at Testing.
Regardless of when you choose to write your tests, they must be present in your submission to the Carbonite team.
Documentation is also a must. A guide to writing suitable documentation can be found at documenting.
Users must be informed of your changes. This is accomplished by updating the following files:
CHANGES.md
VERSION
See CHANGES.md to understand when/how to update those files.
Wash. Rinse. Repeat as needed.
A broad understanding of Carbonite can be gained by reading Omniverse Native Interfaces and Architecture.
Likewise, please consult our style guide before submitting code.
Note
We welcome contributions that rely on third party software. See XXX to understand how to reliably ingest third party libraries and navigate potential licensing issues.
Committing / Pushing Changes¶
As you code in your local clone of your Carbonite fork, it’s encouraged to often commit changes:
git commit -a
Feel free to commit as much as you like. During the “Merge Request” process described below, all of your commits will be combined into a single commit visible to others.
Once you’re ready to submit a Merge Request, or just want to backup your work on the server, push your changes:
git push origin HEAD
Submitting Your Contribution as a Merge Request (MR)¶
Before your contribution becomes a part of the Omniverse Carbonite SDK, it must be peer reviewed. This is done through a “Merge Request” (MR).
To submit a MR, navigate to your Carbonite fork’s Merge Request page. Assuming your username is “ncournia”:
Press the green “New merge request” button.
The “Source branch” should be a combination name of your fork (e.g. “ncournia/carbonite” above) and the name of your feature branch (e.g. “feature/ncournia/omni.bind-doc-fix” above).
“Target branch” should default to the correct settings: “omniverse/carbonite” and “master”.
Select “Compare branches and continue”.
You’ll now be asked to enter a title and description for your submission.
The title should be the Jira issue number and title from the Jira issue you created before starting your contribution. For example:
OM-28142: omni.bind: Only update copyright when needed
Above the issue number, OM-28142, is the important part. This allows our tooling to associate the Merge Request with the Jira task.
Write a helpful description and then push the green “Submit merge request” button.
CI/CT/CD¶
Once a MR is submitted, it will automatically be built on TeamCity. If any builds or tests fail, you will need to fix them and push new changes. New pushes will automatically restart the CI/CT/CD process.
Once a build has been completed, you will be able to access your documentation at https://nv/carb-docs/<your MR number>.
The latest documentation is available at https://nv/carb-docs/latest.
Addressing Feedback¶
The review process will result in requests by fellow engineers to fix potential bugs, justify the codes existence, clarify documentation, increase test coverage, etc. In order for your submission to be accepted, you will be expected to address any feedback given. You can address feedback by either fixing any issues brought up or by explaining why the feedback does not need to be addressed. Before a contribution is accepted, consensus must be reached.
Merging Your Contribution¶
Once all feedback has been addressed and consensus has been reached, a Carbonite team member will “Approve” the request. You can now press the green “Merge” button to have your contribution become a part of the Omniverse Carbonite SDK.
Publishing a New Carbonite Package¶
Reach out to the Carbonite team to have a new package containing your contribution distributed to the public.