Welcome to OpenUSD-proposals, a forum for sharing and collaborating on proposals for the advancement of USD.
Before getting started, please familiarize yourself with the contents of the Supplemental Terms page.
If you are interested in browsing existing proposals, please proceed right to the current list of proposals, with status information.
- A new schema, such as "Level of Detail for Games"
- An outline for a technical action, such as "Removing the usage of boost preprocessor macros"
- A new development, such as "Evaluation of Hermite Patches"
- A discussion of scope tightening, such as "Standardizing Alembic without HDF5"
For inspiration, here are several proposals that have been recently published and implemented, and some Pixar proposals that have previously been worked through.
- Submit a PR with your proposal
- Engage the community in discussion
- Understand and address community comments
- Shepherd proposal through to publication
- (If applicable) Submit a proposed implementation to OpenUSD
The diagram below offers a visual representation of the proposal process. The proposal's PR status provides a general sense of where a proposal sits in the approval workflow while more specific proposal statuses add detail. You can monitor your proposal status using the OpenUSD Proposals Status page.
sequenceDiagram
To Do->>+Draft: Pixar initial review
To Do->>+Draft: Community review
Draft-->>+Hold: Core proposal needs more iteration
Hold-->>-Draft: Pixar core concerns addressed
Draft->>+Finalizing: Pixar & community comments addressed
Finalizing->>+Published: Final cleanup
Published->>+Implemented: Implementation in OpenUSD
To Do-->>+Hold: Core proposal needs more iteration
To Do-->>+Closed: Proposal retracted
Draft-->>+Closed: Proposal retracted
Hold-->>+Closed: Proposal retracted
Finalizing-->>+Closed: Proposal retracted
Open PRs indicate that a proposal is still open for comments and changes.
- New PRs are automatically given the To do status. This indicates the proposal is still in triage and has not yet been reviewed.
- When the proposal is changed to the Draft status, this indicates the proposal has gone through an initial review and is ready to be discussed with the broader community.
- A proposal may be moved to Hold status if the proposal needs more iteration and/or broader consensus from the community.
- Proposals move to the Finalizing status when the proposal is nearing publication and the commentary period is closing soon.
Merged PRs indicate that a proposal has been accepted. Any changes to proposals that have already been merged will need to be filed as new PRs that reference back to the relevant proposal.
- Once a proposal is considered complete and fully reviewed, it will be merged and moved to Published status. This indicates the proposal can be used as a starting point for implementation.
- Once implementation work has been completed, the proposal will be moved to Implemented status, with indication of which version of USD the proposal was implemented in.
Exception: Proposals in the _notPublished folder are still open for comments and changes. These are proposals that were merged into the repo as part of a legacy process. The subfolders (draft vs hold) indicate the proposal's actual status.
Closed PRs indicate that a proposal has been retracted and is not continuing through to publication/implementation. These proposals will automatically get a Closed status and a new pull request will have to be submitted if there's renewed interest in the proposal idea later.
| Status | Meaning |
|---|---|
| To do | Proposal needs to be triaged |
| Draft | Proposal is work-in-progress, open for feedback and reviews |
| Finalizing | Proposal has been discussed and is close to finalized |
| Published | Proposal is approved as a starting point for implementation |
| Implemented | Proposal has been implemented |
| Hold | Proposal needs further iteration and/or broader community consensus |
| Closed | Proposal has been retracted |
- Fork this repo.
- Create a directory within
proposals/for the proposal and its materials, and a README.md.- The README.md document may contain the proposal, or at a minimum, it should announce the contents of the proposal and how to understand the materials within the proposal.
- The README.md should also contain notes the author considers important for anyone looking at the proposal, which could include notes that a proposal has been superseded by another, that the proposal resulted in a change to another project, and so on.
- Submit a PR and fill out the provided sections in the pull request body.
- The PR may include links to supporting materials that could not be included with the proposal files, such as white papers. Add links to the "Supporting Materials" section of the PR body.
- Please mention and link any issues and PRs in OpenUSD or OpenUSD-proposals that are related to the new proposal. A label will be created to link relevant discussions together.
When writing and submitting a proposal, we make the following suggestions for receiving the best feedback.
- Include a link to the rendered proposal in your PR description. This can be as simple as linking to the markdown file in your source branch. This makes it significantly easier for someone to read the document in a well formatted way.
- Your PR and proposal should include, and ideally start with, a short summary of what your change would achieve. The pull request template offers a possible structure for reference.
- It is highly recommended that any submitted proposal include text examples of
what your proposal would look like in
.usdasyntax. - It's recommended that long sentences be split over multiple lines in your Markdown file. This allows more granular feedback, and easier viewing of the files.
Some proposals are inherently of significant size. In those case it is recommended to do one or both of the following:
- Split your proposal into multiple smaller proposals.
- Create a sub-proposal PR per major feature.
- Create an umbrella proposal that links to each sub-proposal, ordered by their priority and dependency on each other.
- Divide your proposal into smaller sections. These can be sections within the same document or separate documents.
This helps make each section easier to digest and provide feedback on.
A typical workflow for the proposal PR will have some initial discussion on the PR itself. It’s recommended to bring up the proposal in an ASWF USD Working Group meeting or in the AOUSD Forum to give greater visibility to the proposal and engage the community in discussion.
Note that at any point, proposal text may be used in other contexts. For example, a proposal may be referenced when writing new schemas or code for USD. Referencing a proposal in this way does not guarantee that the proposal will advance beyond a discussion stage.
When a proposal has been approved as a starting point for implementation, that will be noted here with a “Published” proposal status.
Subsequent development should occur in the appropriate forums. For example, if a proposal has been developed into code and concrete schemas, that might become a pull request against the main OpenUSD repo (see contributing guidelines). Such a development should be noted in the proposal's README.md file and linked to the pull request in the main OpenUSD repo.
The success of the forum is predicated on involvement and communication, so consider this an appeal to everyone's creativity and thoughtful consideration.
Civility, inclusiveness, friendship, and constructive collaboration shall be the hallmarks of this forum.
Thank you for your participation!