2017-11-24 14:33:18 +00:00
|
|
|
# Contributing to SPIR-V Tools
|
|
|
|
|
|
|
|
## For users: Reporting bugs and requesting features
|
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
We organize known future work in GitHub projects. See [Tracking SPIRV-Tools work
|
|
|
|
with GitHub
|
|
|
|
projects](https://github.com/KhronosGroup/SPIRV-Tools/blob/master/projects.md)
|
|
|
|
for more.
|
2017-11-24 14:33:18 +00:00
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
To report a new bug or request a new feature, please file a GitHub issue. Please
|
|
|
|
ensure the bug has not already been reported by searching
|
|
|
|
[issues](https://github.com/KhronosGroup/SPIRV-Tools/issues) and
|
|
|
|
[projects](https://github.com/KhronosGroup/SPIRV-Tools/projects). If the bug has
|
|
|
|
not already been reported open a new one
|
|
|
|
[here](https://github.com/KhronosGroup/SPIRV-Tools/issues/new).
|
2017-11-24 14:33:18 +00:00
|
|
|
|
|
|
|
When opening a new issue for a bug, make sure you provide the following:
|
|
|
|
|
|
|
|
* A clear and descriptive title.
|
2017-12-01 17:17:47 +00:00
|
|
|
* We want a title that will make it easy for people to remember what the
|
|
|
|
issue is about. Simply using "Segfault in spirv-opt" is not helpful
|
|
|
|
because there could be (but hopefully aren't) multiple bugs with
|
|
|
|
segmentation faults with different causes.
|
|
|
|
* A test case that exposes the bug, with the steps and commands to reproduce
|
|
|
|
it.
|
|
|
|
* The easier it is for a developer to reproduce the problem, the quicker a
|
|
|
|
fix can be found and verified. It will also make it easier for someone
|
|
|
|
to possibly realize the bug is related to another issue.
|
|
|
|
|
|
|
|
For feature requests, we use
|
|
|
|
[issues](https://github.com/KhronosGroup/SPIRV-Tools/issues) as well. Please
|
|
|
|
create a new issue, as with bugs. In the issue provide
|
2017-11-24 14:33:18 +00:00
|
|
|
|
|
|
|
* A description of the problem that needs to be solved.
|
|
|
|
* Examples that demonstrate the problem.
|
|
|
|
|
|
|
|
## For developers: Contributing a patch
|
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
Before we can use your code, you must sign the [Khronos Open Source Contributor
|
|
|
|
License Agreement](https://cla-assistant.io/KhronosGroup/SPIRV-Tools) (CLA),
|
|
|
|
which you can do online. The CLA is necessary mainly because you own the
|
|
|
|
copyright to your changes, even after your contribution becomes part of our
|
|
|
|
codebase, so we need your permission to use and distribute your code. We also
|
|
|
|
need to be sure of various other things -- for instance that you'll tell us if
|
|
|
|
you know that your code infringes on other people's patents. You don't have to
|
|
|
|
sign the CLA until after you've submitted your code for review and a member has
|
|
|
|
approved it, but you must do it before we can put your code into our codebase.
|
|
|
|
|
|
|
|
See
|
|
|
|
[README.md](https://github.com/KhronosGroup/SPIRV-Tools/blob/master/README.md)
|
|
|
|
for instruction on how to get, build, and test the source. Once you have made
|
|
|
|
your changes:
|
|
|
|
|
|
|
|
* Ensure the code follows the [Google C++ Style
|
|
|
|
Guide](https://google.github.io/styleguide/cppguide.html). Running
|
|
|
|
`clang-format -style=file -i [modified-files]` can help.
|
2017-11-24 14:33:18 +00:00
|
|
|
* Create a pull request (PR) with your patch.
|
2017-12-01 17:17:47 +00:00
|
|
|
* Make sure the PR description clearly identified the problem, explains the
|
|
|
|
solution, and references the issue if applicable.
|
2017-12-21 16:25:31 +00:00
|
|
|
* If your patch completely fixes bug 1234, the commit message should say
|
|
|
|
`Fixes https://github.com/KhronosGroup/SPIRV-Tools/issues/1234`
|
|
|
|
When you do this, the issue will be closed automatically when the commit
|
|
|
|
goes into master. Also, this helps us update the [CHANGES](CHANGES) file.
|
2017-11-24 14:33:18 +00:00
|
|
|
* Watch the continuous builds to make sure they pass.
|
|
|
|
* Request a code review.
|
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
The reviewer can either approve your PR or request changes. If changes are
|
|
|
|
requested:
|
2017-11-24 14:33:18 +00:00
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
* Please add new commits to your branch, instead of amending your commit.
|
|
|
|
Adding new commits makes it easier for the reviewer to see what has changed
|
|
|
|
since the last review.
|
|
|
|
* Once you are ready for another round of reviews, add a comment at the
|
|
|
|
bottom, such as "Ready for review" or "Please take a look" (or "PTAL"). This
|
|
|
|
explicit handoff is useful when responding with multiple small commits.
|
2017-11-24 14:33:18 +00:00
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
After the PR has been reviewed it is the job of the reviewer to merge the PR.
|
|
|
|
Instructions for this are given below.
|
2017-11-24 14:33:18 +00:00
|
|
|
|
|
|
|
## For maintainers: Reviewing a PR
|
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
The formal code reviews are done on GitHub. Reviewers are to look for all of the
|
|
|
|
usual things:
|
2017-11-24 14:33:18 +00:00
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
* Coding style follows the [Google C++ Style
|
|
|
|
Guide](https://google.github.io/styleguide/cppguide.html)
|
2017-11-24 14:33:18 +00:00
|
|
|
* Identify potential functional problems.
|
|
|
|
* Identify code duplication.
|
|
|
|
* Ensure the unit tests have enough coverage.
|
2018-07-10 18:59:03 +00:00
|
|
|
* Ensure continuous integration (CI) bots run on the PR. If not run (in the
|
|
|
|
case of PRs by external contributors), add the "kokoro:run" label to the
|
|
|
|
pull request which will trigger running all CI jobs.
|
2017-11-24 14:33:18 +00:00
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
When looking for functional problems, there are some common problems reviewers
|
|
|
|
should pay particular attention to:
|
|
|
|
|
|
|
|
* Does the code work for both Shader (Vulkan and OpenGL) and Kernel (OpenCL)
|
|
|
|
scenarios? The respective SPIR-V dialects are slightly different.
|
|
|
|
* Changes are made to a container while iterating through it. You have to be
|
|
|
|
careful that iterators are not invalidated or that elements are not skipped.
|
|
|
|
* C++11 and VS2013. We generally assume that we have a C++11 compliant
|
|
|
|
compiler. However, on Windows, we still support Visual Studio 2013, which is
|
|
|
|
not fully C++11 compliant. See
|
|
|
|
[here](https://msdn.microsoft.com/en-us/library/hh567368.aspx). In
|
|
|
|
particular, note that it does not provide default move-constructors or
|
|
|
|
move-assignments for classes. In general, r-value references do not work the
|
|
|
|
way you might assume they do.
|
|
|
|
* For SPIR-V transforms: The module is changed, but the analyses are not
|
|
|
|
updated. For example, a new instruction is added, but the def-use manager is
|
|
|
|
not updated. Later on, it is possible that the def-use manager will be used,
|
|
|
|
and give wrong results.
|
2017-11-24 14:33:18 +00:00
|
|
|
|
|
|
|
## For maintainers: Merging a PR
|
|
|
|
|
2017-12-01 17:17:47 +00:00
|
|
|
We intend to maintain a linear history on the GitHub master branch, and the
|
|
|
|
build and its tests should pass at each commit in that history. A linear
|
|
|
|
always-working history is easier to understand and to bisect in case we want to
|
|
|
|
find which commit introduced a bug.
|
2017-11-24 14:33:18 +00:00
|
|
|
|
2017-12-01 18:10:34 +00:00
|
|
|
### Initial merge setup
|
2017-11-24 14:33:18 +00:00
|
|
|
|
2017-12-01 18:10:34 +00:00
|
|
|
The following steps should be done exactly once (when you are about to merge a
|
|
|
|
PR for the first time):
|
|
|
|
|
|
|
|
* It is assumed that upstream points to
|
|
|
|
[git@github.com](mailto:git@github.com):KhronosGroup/SPIRV-Tools.git or
|
|
|
|
https://github.com/KhronosGroup/SPIRV-Tools.git.
|
|
|
|
|
|
|
|
* Find out the local name for the main github repo in your git configuration.
|
|
|
|
For example, in this configuration, it is labeled `upstream`.
|
2017-11-24 14:33:18 +00:00
|
|
|
|
|
|
|
```
|
2017-12-01 18:10:34 +00:00
|
|
|
git remote -v
|
|
|
|
[ ... ]
|
|
|
|
upstream https://github.com/KhronosGroup/SPIRV-Tools.git (fetch)
|
|
|
|
upstream https://github.com/KhronosGroup/SPIRV-Tools.git (push)
|
2017-11-24 14:33:18 +00:00
|
|
|
```
|
|
|
|
|
2017-12-01 18:10:34 +00:00
|
|
|
* Make sure that the `upstream` remote is set to fetch from the `refs/pull`
|
|
|
|
namespace:
|
2017-12-01 17:17:47 +00:00
|
|
|
|
2017-12-01 18:10:34 +00:00
|
|
|
```
|
|
|
|
git config --get-all remote.upstream.fetch
|
|
|
|
+refs/heads/*:refs/remotes/upstream/*
|
|
|
|
+refs/pull/*/head:refs/remotes/upstream/pr/*
|
|
|
|
```
|
|
|
|
|
|
|
|
* If the line `+refs/pull/*/head:refs/remotes/upstream/pr/*` is not present in
|
|
|
|
your configuration, you can add it with the command:
|
2017-11-24 14:33:18 +00:00
|
|
|
|
|
|
|
```
|
2017-12-01 18:10:34 +00:00
|
|
|
git config --local --add remote.upstream.fetch '+refs/pull/*/head:refs/remotes/upstream/pr/*'
|
2017-11-24 14:33:18 +00:00
|
|
|
```
|
|
|
|
|
2017-12-01 18:10:34 +00:00
|
|
|
### Merge workflow
|
|
|
|
|
|
|
|
The following steps should be done for every PR that you intend to merge:
|
|
|
|
|
2017-11-24 14:33:18 +00:00
|
|
|
* Make sure your local copy of the master branch is up to date:
|
|
|
|
|
|
|
|
```
|
2017-12-01 18:10:34 +00:00
|
|
|
git checkout master
|
2017-11-24 14:33:18 +00:00
|
|
|
git pull
|
|
|
|
```
|
|
|
|
|
2017-12-01 18:10:34 +00:00
|
|
|
* Fetch all pull requests refs:
|
|
|
|
|
|
|
|
```
|
|
|
|
git fetch upstream
|
|
|
|
```
|
|
|
|
|
|
|
|
* Checkout the particular pull request you are going to review:
|
2017-12-01 17:17:47 +00:00
|
|
|
|
2017-11-24 14:33:18 +00:00
|
|
|
```
|
2017-12-01 18:10:34 +00:00
|
|
|
git checkout pr/1048
|
2017-11-24 14:33:18 +00:00
|
|
|
```
|
2017-12-01 17:17:47 +00:00
|
|
|
|
2017-12-01 18:10:34 +00:00
|
|
|
* Rebase the PR on top of the master branch. If there are conflicts, send it
|
|
|
|
back to the author and ask them to rebase. During the interactive rebase be
|
|
|
|
sure to squash all of the commits down to a single commit.
|
2017-11-24 14:33:18 +00:00
|
|
|
|
|
|
|
```
|
2017-12-01 18:10:34 +00:00
|
|
|
git rebase -i master
|
2017-11-24 14:33:18 +00:00
|
|
|
```
|
2017-12-01 17:17:47 +00:00
|
|
|
|
2017-12-01 18:10:34 +00:00
|
|
|
* **Build and test the PR.**
|
2017-12-01 17:17:47 +00:00
|
|
|
|
|
|
|
* If all of the tests pass, push the commit `git push upstream HEAD:master`
|
|
|
|
|
|
|
|
* Close the PR and add a comment saying it was push using the commit that you
|
|
|
|
just pushed. See https://github.com/KhronosGroup/SPIRV-Tools/pull/935 as an
|
|
|
|
example.
|