1## How to Contribute to Vulkan Source Repositories 2 3### **The Repositories** 4 5The source code for various Vulkan components is distributed across several GitHub repositories. 6The repositories sponsored by Khronos and LunarG are described here. 7In general, the canonical Vulkan Loader and Validation Layers sources are in the Khronos repository, 8while the LunarG repositories host sources for additional tools and sample programs. 9 10* [Khronos Vulkan-LoaderAndValidationLayers](https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers) 11* [LunarG VulkanTools](https://github.com/LunarG/VulkanTools) 12* [LunarG VulkanSamples](https://github.com/LunarG/VulkanSamples) 13 14As a convenience, the contents of the Vulkan-LoaderAndValidationLayers repository are downstreamed into the VulkanTools and VulkanSamples repositories via a branch named `trunk`. 15This makes the VulkanTools and VulkanSamples easier to work with and avoids compatibility issues 16that might arise with Vulkan-LoaderAndValidationLayers components if they were obtained from a separate repository. 17 18### **We Do Need Your Help** 19 20The Vulkan validation layers are one of the larger and more important components in this repository. 21While there are often active and organized development efforts underway to improve their coverage, 22there are always opportunities for anyone to help by contributing additional validation layer checks 23and tests for these validation checks. 24If you desire to help in this area, please examine the 25[issues list](https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/issues) 26in this repository and look for any unassigned issues that are of interest to you. 27Of course, if you have your own work in mind, please open an issue to describe it and assign it to yourself. 28Finally, please feel free to contact any of the developers that are actively contributing should you 29wish to coordinate further. 30Please see the [section about Validation Layers](#special-considerations-for-validation-layers) 31later on this page. 32 33### **How to Submit Fixes** 34 35* **Ensure that the bug was not already reported or fixed** by searching on GitHub under Issues 36 and Pull Requests. 37* Use the existing GitHub forking and pull request process. 38 This will involve [forking the repository](https://help.github.com/articles/fork-a-repo/), 39 creating a branch with your commits, and then [submitting a pull request](https://help.github.com/articles/using-pull-requests/). 40* Please base your fixes on the master branch. SDK branches are generally not updated except for critical fixes needed to repair an SDK release. 41* Please include the GitHub Issue number near the beginning of the commit text if applicable. 42 * Example: "GitHub 123: Fix missing init" 43* If your changes are restricted only to files from the Vulkan-LoaderAndValidationLayers repository, please direct your pull request to that repository, instead of VulkanTools or VulkanSamples. 44 45 46#### **Coding Conventions and Formatting** 47* Try to follow any existing style in the file. "When in Rome..." 48* Run clang-format on your changes to maintain formatting. 49 * There are `.clang-format files` throughout the repository to define clang-format settings 50 which are found and used automatically by clang-format. 51 * A sample git workflow may look like: 52 53> # Make changes to the source. 54> $ git add -u . 55> $ git clang-format --style=file 56> # Check to see if clang-format made any changes and if they are OK. 57> $ git add -u . 58> $ git commit 59 60#### **Testing** 61* Run the existing tests in the repository before and after your changes to check for any regressions. 62 There are some tests that appear in all repositories. 63 These tests can be found in the following folders inside of your target build directory: 64 (These instructions are for Linux) 65* In the `demos` directory, run: 66 67> cube 68> cube --validate 69> smoke 70> smoke --validate 71> vulkaninfo 72 73* In the `tests` directory, run: 74 75> run_all_tests.sh 76 77* Note that some tests may fail with known issues or driver-specific problems. 78 The idea here is that your changes shouldn't change the test results, unless that was the intent of your changes. 79* Run tests that explicitly exercise your changes. 80* Feel free to subject your code changes to other tests as well! 81 82#### **Special Considerations for Validation Layers** 83If you are submitting a change that adds a new validation check, you should also construct a "negative" test function. 84The negative test function purposely violates the validation rule that the new validation check is looking for. 85The test should cause your new validation check to identify the violation and issue a validation error report. 86And finally, the test should check that the validation error report is generated and consider the test as "passing" 87if the report is received. Otherwise, the test should indicate "failure". 88This new test should be added to the validation layer test program in the `tests` directory and contributed 89at the same time as the new validation check itself. 90There are many existing validation tests in this directory that can be used as a starting point. 91 92 93### **Contributor License Agreement (CLA)** 94 95You'll be prompted with a one-time "click-through" CLA dialog as part of submitting your pull request 96or other contribution to GitHub. 97 98### **License and Copyrights** 99 100All contributions made to the Vulkan-LoaderAndValidationLayers repository are Khronos branded and as such, 101any new files need to have the Khronos license (Apache 2.0 style) and copyright included. 102Please see an existing file in this repository for an example. 103 104All contributions made to the LunarG repositories are to be made under the Apache 2.0 license 105and any new files need to include this license and any applicable copyrights. 106 107You can include your individual copyright after any existing copyrights. 108