forked from AcademySoftwareFoundation/MaterialX
-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into fix_normalmap_nodedef_upgrade
- Loading branch information
Showing
34 changed files
with
1,290 additions
and
105 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| name: release | ||
|
|
||
| on: | ||
| release: | ||
| types: [published] | ||
|
|
||
| permissions: | ||
| contents: read | ||
|
|
||
| jobs: | ||
|
|
||
| release: | ||
| name: Release Signing | ||
| runs-on: ubuntu-latest | ||
| env: | ||
| RELEASE_TAG: ${{ github.ref_name }} | ||
| permissions: | ||
| contents: write | ||
| id-token: write | ||
| repository-projects: write | ||
|
|
||
| steps: | ||
| - name: Sync Repository | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| submodules: recursive | ||
|
|
||
| - name: Create Archive Name | ||
| run: echo "MATERIALX_ARCHIVE=MaterialX-${RELEASE_TAG//v}" >> $GITHUB_ENV | ||
|
|
||
| - name: Generate Archives | ||
| run: | | ||
| git archive --prefix ${MATERIALX_ARCHIVE}/ --output ${MATERIALX_ARCHIVE}.zip ${RELEASE_TAG} | ||
| git archive --prefix ${MATERIALX_ARCHIVE}/ --output ${MATERIALX_ARCHIVE}.tar.gz ${RELEASE_TAG} | ||
| - name: Sign and Upload Archives | ||
| uses: sigstore/[email protected] | ||
| with: | ||
| inputs: | | ||
| ${{ env.MATERIALX_ARCHIVE }}.zip | ||
| ${{ env.MATERIALX_ARCHIVE }}.tar.gz | ||
| upload-signing-artifacts: true | ||
| release-signing-artifacts: false |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,33 +1,214 @@ | ||
| # Contributing to MaterialX | ||
|
|
||
| Thank you for your interest in contributing to MaterialX! This document explains our contribution process and procedures. | ||
| Thank you for your interest in contributing to MaterialX! This document | ||
| explains our contribution process and procedures. | ||
|
|
||
| ## Community and Discussion | ||
|
|
||
| There are two primary ways to connect with the MaterialX community: | ||
|
|
||
| * The MaterialX channel of the [Academy Software Foundation Slack](http://academysoftwarefdn.slack.com/). 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://slack.aswf.io/. | ||
| * The [Issues](https://github.com/AcademySoftwareFoundation/MaterialX/issues) panel of the MaterialX GitHub, which is used to report and discuss bugs and build issues. | ||
| - The MaterialX channel of the | ||
| [Academy Software Foundation Slack](http://academysoftwarefdn.slack.com/). | ||
| 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](https://github.com/AcademySoftwareFoundation/MaterialX/issues) | ||
| panel of the MaterialX GitHub, which is used both to track bugs and to discuss | ||
| feature requests. | ||
|
|
||
| ## Contributor License Agreements | ||
| ### How to Ask for Help | ||
|
|
||
| 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. | ||
| 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](http://academysoftwarefdn.slack.com/). | ||
| This is the place for questions such has "How do I...". | ||
|
|
||
| Prior to submitting a pull request, you can sign the form through [this link](https://contributor.easycla.lfx.linuxfoundation.org/#/cla/project/68fa91fe-51fe-41ac-a21d-e0a0bf688a53/user/564e571e-12d7-4857-abd4-898939accdd7). 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. | ||
| ### How to Report a Bug | ||
|
|
||
| * 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. | ||
| MaterialX uses | ||
| [GitHub Issues](https://github.com/AcademySoftwareFoundation/MaterialX/issues) | ||
| for reporting and tracking bugs, enhancements, and feature requests. | ||
|
|
||
| The MaterialX CLAs are the standard forms used by Linux Foundation projects and [recommended by the ASWF TAC](https://github.com/AcademySoftwareFoundation/tac/blob/main/process/contributing.md#contributor-license-agreement-cla). | ||
| 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: | ||
|
|
||
| ## Coding Conventions | ||
| - What you tried. | ||
| - What happened. | ||
| - What you expected to happen instead. | ||
|
|
||
| The coding style of the MaterialX project is defined by a [clang-format](.clang-format) file in the repository, which is supported by Clang versions 13 and newer. | ||
| ### How to Report a Security Vulnerability | ||
|
|
||
| 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. | ||
| If you think you've found a potential vulnerability in MaterialX, please refer | ||
| to [SECURITY.md](SECURITY.md) to responsibly disclose it. | ||
|
|
||
| ## Unit Tests | ||
| ### How to Contribute a Bug Fix or Change | ||
|
|
||
| Each MaterialX module has a companion folder within the [MaterialXTest](source/MaterialXTest) module, containing a set of unit tests that validate its functionality. | ||
| To contribute code to the project, you'll need: | ||
|
|
||
| When contributing new code to MaterialX, make sure to include appropriate unit tests in MaterialXTest to validate the expected behavior of the new code. | ||
| - 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. | ||
|
|
||
| ## Legal Requirements | ||
|
|
||
| MaterialX is a project of the Academy Software Foundation and follows the | ||
| open source software best practice policies of the Linux Foundation. | ||
|
|
||
| ### License | ||
|
|
||
| MaterialX is licensed under the [Apache 2.0](LICENSE.md) license. | ||
| Contributions to the project should abide by that standard license. | ||
|
|
||
| ### Contributor License Agreements | ||
|
|
||
| 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](https://contributor.easycla.lfx.linuxfoundation.org/#/cla/project/68fa91fe-51fe-41ac-a21d-e0a0bf688a53/user/564e571e-12d7-4857-abd4-898939accdd7). | ||
| 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](https://github.com/AcademySoftwareFoundation/tac/blob/main/process/contributing.md#contributor-license-agreement-cla). | ||
|
|
||
| ## Development Workflow | ||
|
|
||
| ### Git Basics | ||
|
|
||
| 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](https://help.github.com/articles/github-glossary/) or | ||
| browse [GitHub Help](https://help.github.com/). | ||
|
|
||
| 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](https://git-scm.com/doc) or a Git client such | ||
| as [Git Fork](https://git-fork.com/) or | ||
| [GitHub Desktop](https://desktop.github.com/download/) installed | ||
| on your local development machine. | ||
|
|
||
| ### Repository Structure and Commit Policy | ||
|
|
||
| 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](https://github.com/AcademySoftwareFoundation/MaterialX/releases) | ||
| of the project. | ||
|
|
||
| ### Use the Fork, Luke. | ||
|
|
||
| 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](https://help.github.com/articles/cloning-a-repository/) | ||
| and | ||
| [Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/). | ||
|
|
||
| ### Pull Requests | ||
|
|
||
| Contributions should be submitted as GitHub pull requests. See | ||
| [Creating a pull request](https://help.github.com/articles/creating-a-pull-request/) | ||
| if you're unfamiliar with this concept. | ||
|
|
||
| The development cycle for a code change should follow this protocol: | ||
|
|
||
| 1. 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. | ||
| 2. 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. | ||
| 3. Push commits to your fork. | ||
| 4. Create a GitHub pull request from your topic branch. | ||
| 5. Pull requests will be reviewed by project maintainers and contributors, | ||
| who may discuss, offer constructive feedback, request changes, or approve | ||
| the work. | ||
| 6. Upon receiving the required number of approvals (as outlined in | ||
| [Required Approvals](#code-review-and-required-approvals)), a maintainer | ||
| may merge changes into the `main` branch. | ||
|
|
||
| ### Code Review and Required Approvals | ||
|
|
||
| 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. | ||
|
|
||
| ### Coding Conventions | ||
|
|
||
| The coding style of the MaterialX project is defined by a | ||
| [clang-format](.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. | ||
|
|
||
| ### Unit Tests | ||
|
|
||
| Each MaterialX module has a companion folder within the | ||
| [MaterialXTest](source/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. |
Oops, something went wrong.