Skip to content

Latest commit

 

History

History
111 lines (92 loc) · 5.99 KB

CONTRIBUTING.md

File metadata and controls

111 lines (92 loc) · 5.99 KB
Raw

Contribution guidelines

If you have found a bug or would like to see a new feature

Please reach us by creating a new issue.

Your bug report should include a proper description and steps to reproduce:

  • attach the LLVM BC or SPV file you are trying to translate and the command you launch
  • any backtrace in case of crashes would be helpful
  • please describe what goes wrong or what is unexpected during translation

For feature requests, please describe the feature you would like to see implemented in the translator.

If you would like to contribute your change

Please open a pull request. If you are not sure whether your changes are correct, you can either mark it as draft or create an issue to discuss the problem and possible ways to fix it prior to publishing a PR.

It is okay to have several commits in the PR, but each of them should be buildable and tests should pass. Maintainers can squash several commits into a single one for you during merge, but if you would like to see several commits in the git history, please let us know in PR description/comments so maintainers will rebase your PR instead of squashing it.

Each functional change (new feature or bug fix) must be supplied with corresponding tests. See [#testing-guidelines] for more information about testing. NFC (non-functional change) PRs can be accepted without new tests.

Code changes should follow coding standards, which are inherited from LLVM Coding Standards. Compliance of your code is checked automatically using GitHub Actions. See clang-format and clang-tidy configs for more details about coding standards.

How to add an extension

First of all please make sure you have added a link to the specification for the extension in your PR. Then to add definitions of new Op Codes you shall modify spirv.hpp, which is an external dependency for this project. To do so, you should add new definitions to json grammar file, rebuild the header following the instructions in SPIR-V Headers repository and push your changes for review, i.e. make a PR. Once the PR is merged, a new spirv.hpp will have to be downloaded during build of the translator; make sure to update the hash for SPIRV-Headers in [spirv-headers-tag.conf] so that tokens from your extension can be visible to the translator build.

It's highly recommended to add the definitions to SPIR-V Headers repository first, but if you don't want to bring it there yet, you can define new Op Codes in the internal SPIR-V header file.

For local testing you can copy your spirv.hpp variant to <PATH_TO_SPIRV_HEADERS>/include/spirv/unified1 and/or modify it there. See README.md for build instructions that should be employed with such modifications.

Conditions to merge a PR

In order to get your PR merged, the following conditions must be met:

  • If you are a first-time contributor, you have to sign the Contributor License Agreement. Corresponding link and instructions will be automatically posted into your PR.
  • GitHub CI testing jobs must pass on your PR: this includes functional testing and checking for complying with coding standards.
  • You need to get approval from at least one contributor with merge rights.

As a contributor, you should expect that even an approved PR might still be left open for a few days: this is needed, because the translator is being developed by different vendors and individuals and we need to ensure that each interested party is able to react to new changes and provide feedback.

Information below is a guideline for repo maintainers and can be used by contributors to get some expectations about how long a PR has to be open before it can be merged:

  • For any significant change/redesign, the PR must be open for at least 5 working days, so everyone interested can step in to provide feedback, discuss direction and help to find bugs.
    • Ideally, there should be approvals from different vendors/individuals to get it merged, particularly for larger changes.
  • For regular changes/bug fixes, the PR must be open for at least 2-3 working days, so everyone interested can step in for review and provide feedback.
    • If the change is vendor-specific (bug fix in vendor extension implementation or new vendor-specific extension support), then it is okay to merge PR sooner.
    • If the change affects or might affect several interested parties, the PR must be left open for 2-3 working days and it would be good to see feedback from different vendors/inviduals before merging.
  • Tiny NFC changes or trivial build fixes (due to LLVM API changes) can be submitted as soon as testing is finished and PR approved - no need to wait for too long.
  • In general, just use common sense to wait long enough to get feedback from everyone who might be interested in the PR and don't hesitate to explicitly mention individuals who might be interested in reviewing the PR.