Thank you for your interest in contributing to MaterialX! This document explains our contribution process and procedures.
There are two primary ways to connect with the MaterialX community:
- The MaterialX channel of the Academy Software Foundation Slack. This platform is appropriate for general questions, feature requests, and discussion of the MaterialX project as a whole. You can request an invitation to join the Academy Software Foundation Slack at https://www.aswf.io/get-involved/.
- The Issues panel of the MaterialX GitHub, which is used both to track bugs and to discuss feature requests.
If you have trouble installing, building, or using the library, but there's not yet reason to suspect you've encountered a genuine bug, start by posting a question to the MaterialX channel of the Academy Software Foundation Slack. This is the place for questions such has "How do I...".
MaterialX uses GitHub Issues for reporting and tracking bugs, enhancements, and feature requests.
If you are submitting a bug report, please be sure to note which version of MaterialX you are using, on what platform (OS/version, which compiler you used, and any special build flags or other unusual environmental issues). Please give a specific account of the following, with enough detail that others can reproduce the problem:
- What you tried.
- What happened.
- What you expected to happen instead.
If you think you've found a potential vulnerability in MaterialX, please refer to SECURITY.md to responsibly disclose it.
To contribute code to the project, you'll need:
- Basic knowledge of Git.
- A fork of the MaterialX repository on GitHub.
- An understanding of the project's development workflow.
- Legal authorization, that is, you need to have signed a contributor License Agreement. See below for details.
MaterialX is a project of the Academy Software Foundation and follows the open source software best practice policies of the Linux Foundation.
MaterialX is licensed under the Apache 2.0 license. Contributions to the project should abide by that standard license.
To contribute to MaterialX, you must sign a Contributor License Agreement through the EasyCLA system, which is integrated with GitHub as a pull request check.
Prior to submitting a pull request, you can sign the form through this link. If you submit a pull request before the form is signed, the EasyCLA check will fail with a red NOT COVERED message, and you'll have another opportunity to sign the form through the provided link.
- If you are an individual writing the code on your own time and you're sure you are the sole owner of any intellectual property you contribute, you can sign the CLA as an Individual Contributor.
- If you are writing the code as part of your job, or if your employer retains ownership to intellectual property you create, then your company's legal affairs representatives should sign a Corporate Contributor License Agreement. If your company already has a signed CCLA on file, ask your local CLA manager to add you to your company's approved list.
The MaterialX CLAs are the standard forms used by Linux Foundation projects and recommended by the ASWF TAC.
Working with MaterialX requires a basic understanding of Git and GitHub terminology. If you’re unfamiliar with these concepts, please look at the GitHub Glossary or browse GitHub Help.
To contribute, you need a GitHub account. This is needed in order to push changes to the upstream repository, via a pull request.
You will also need Git or a Git client such as Git Fork or GitHub Desktop installed on your local development machine.
Development work in the MaterialX project is usually done directly
on the main branch. This branch represents the cutting edge of the
project and the majority of new work is proposed, tested, reviewed,
and merged there.
After sufficient work is done on the main branch and the MaterialX
leadership determines that a release is due, they will mark a release with
the current version tag and increment the development version for future
work. This basic repository structure keeps maintenance low, while remaining
simple to understand.
The main branch may include untested features and is not generally stable
enough for release. To retrieve a stable version of the source code, use any
of the
official releases
of the project.
In a typical workflow, you should fork the MaterialX repository to your account. This creates a copy of the repository under your user namespace and serves as the “home base” for your development branches, from which you will submit pull requests to the upstream repository to be merged.
Once your Git environment is operational, the next step is to locally clone your forked MaterialX repository, and add a remote pointing to the upstream MaterialX repository. These topics are covered in the GitHub documentation Cloning a repository and Configuring a remote for a fork.
Contributions should be submitted as GitHub pull requests. See Creating a pull request if you're unfamiliar with this concept.
The development cycle for a code change should follow this protocol:
- Create a topic branch in your local repository, assigning the branch a brief name that describes the feature or fix that you're working on.
- Make changes, compile, and test thoroughly. Code style should match existing style and conventions, and changes should be focused on the topic the pull request will be addressing. Make unrelated changes in a separate topic branch with a separate pull request.
- Push commits to your fork.
- Create a GitHub pull request from your topic branch.
- Pull requests will be reviewed by project maintainers and contributors, who may discuss, offer constructive feedback, request changes, or approve the work.
- Upon receiving the required number of approvals (as outlined in
Required Approvals), a maintainer
may merge changes into the
mainbranch.
Modifications of the contents of the MaterialX repository are made on a collaborative basis. Anyone with a GitHub account may propose a modification via pull request and it will be considered by the project maintainers.
Pull requests must meet a minimum number of maintainer approvals prior to being merged. Rather than having a hard rule for all PRs, the requirement is based on the complexity and risk of the proposed changes, factoring in the length of time the PR has been open to discussion. The following guidelines outline the project's established approval rules for merging:
- Minor changes that don't modify current behaviors or are straightforward fixes to existing features can be approved and merged by a single maintainer of the repository.
- Moderate changes that modify current behaviors or introduce new features should be approved by two maintainers before merging. Unless the change is an emergency fix, the author should give the community at least 48 hours to review the proposed change.
- Major new features and core design decisions should be discussed at length in the ASWF Slack or in TSC meetings before any PR is submitted, in order to solicit feedback, build consensus, and alert all stakeholders to be on the lookout for the eventual PR when it appears.
The coding style of the MaterialX project is defined by a clang-format file in the repository, which is supported by Clang versions 13 and newer.
When adding new source files to the repository, use the provided clang-format file to automatically align the code to MaterialX conventions. When modifying existing code, follow the surrounding formatting conventions so that new or modified code blends in with the current code.
Each MaterialX module has a companion folder within the MaterialXTest module, containing a set of unit tests that validate its functionality. When contributing new code to MaterialX, make sure to include appropriate unit tests in MaterialXTest to validate the expected behavior of the new code.
The MaterialX test suite can be run locally via MaterialXTest before submitting a pull request. Upon receiving a pull request, the GitHub CI process will automatically run MaterialXTest across all platforms, and a successful result is required before merging a change.