1# How to Contribute to Vulkan Source Repositories 2 3## The Repository 4 5The source code for the Vulkan Loader component is sponsored 6by Khronos and LunarG. 7 8* [KhronosGroup/Vulkan-Loader](https://github.com/KhronosGroup/Vulkan-Loader) 9 10### The Vulkan Ecosystem Needs Your Help 11 12There are a couple of methods to identify areas of need: 13 14* Examine the [issues list](https://github.com/KhronosGroup/Vulkan-Loader/issues) 15 in this repository and look for issues that are of interest 16* If you have your own work in mind, please open an issue to describe 17 it and assign it to yourself. 18 19Please feel free to contact any of the developers that are actively 20contributing should you wish to coordinate further. 21 22Repository Issue labels: 23 24* _Bug_: These issues refer to invalid or broken functionality and are 25 the highest priority. 26* _Enhancement_: These issues refer to ideas for extending or improving the 27 loader. 28 29It is the maintainers goal for all issues to be assigned within one business day 30of their submission. 31If you choose to work on an issue that is assigned, simply coordinate with the 32current assignee. 33 34### How to Submit Fixes 35 36* **Ensure that the bug was not already reported or fixed** by searching on 37 GitHub under Issues and Pull Requests. 38* Use the existing GitHub forking and pull request process. 39 This will involve 40 [forking the repository](https://help.github.com/articles/fork-a-repo/), 41 creating a branch with your commits, and then 42 [submitting a pull request](https://help.github.com/articles/using-pull-requests/). 43* Please read and adhere to the style and process 44 [guidelines](#coding-conventions-and-formatting) enumerated below. 45* Please base your fixes on the `main` branch. 46 SDK branches are generally not updated except for critical fixes needed to 47 repair an SDK release. 48* Provide one or more tests which show a failure for the issue before your changes 49 but pass successfully with your changes. 50* The resulting Pull Request will be assigned to a repository maintainer. 51 It is the maintainer's responsibility to ensure the Pull Request 52 passes the Google/LunarG internal CI processes. 53 Once the Pull Request has been approved and is passing internal CI, 54 a repository maintainer will merge the PR. 55 56#### Coding Conventions and Formatting 57 58* Use the 59 **[Google style guide](https://google.github.io/styleguide/cppguide.html)** 60 for source code with the following exceptions: 61 * The column limit is 132 (as opposed to the default value 80). 62 The clang-format tool will handle this. See below. 63 * The indent is 4 spaces instead of the default 2 spaces. 64 Again, the clang-format tool will handle this. 65 * If you can justify a reason for violating a rule in the guidelines, 66 then you are free to do so. Be prepared to defend your 67 decision during code review. This should be used responsibly. 68 An example of a bad reason is "I don't like that rule." 69 An example of a good reason is "This violates the style guide, 70 but it improves type safety." 71 72* Run **clang-format** on your changes to maintain consistent formatting 73 * There are `.clang-format` files present in the repository to define 74 clang-format settings which are found and used automatically by clang-format. 75 * **clang-format** binaries are available from the LLVM orginization, here: 76 [LLVM](https://clang.llvm.org/). 77 Our CI system currently uses clang-format version 16 to 78 check that the lines of code you have changed are formatted properly. 79 It is recommended that you use the same version to format your code prior 80 to submission. 81 * A sample git workflow may look like: 82 83> # Make changes to the source. 84> $ git add -u . 85> $ git clang-format --style=file 86> # Check to see if clang-format made any changes and if they are OK. 87> $ git add -u . 88> $ git commit 89 90* **Commit Messages** 91 * Limit the subject line to 50 characters -- 92 this allows the information to display correctly in git/Github logs 93 * Begin subject line with a one-word component description followed 94 by a colon (e.g. loader, layers, tests, etc.) 95 * Separate subject from body with a blank line 96 * Wrap the body at 72 characters 97 * Capitalize the subject line 98 * Do not end the subject line with a period 99 * Use the body to explain what and why vs. how 100 * Use the imperative mode in the subject line. 101 This just means to write it as a command (e.g. Fix the sprocket) 102 103Strive for commits that implement a single or related set of functionality, 104using as many commits as is necessary (more is better). 105 106Please ensure that the repository compiles and passes tests without 107error for each commit in your pull request. 108Note that to be accepted into the repository, the pull request must 109pass all tests on all supported platforms. 110The automatic Github continuous integration features 111will assist in enforcing this requirement.* 112 113#### Generated Source Code 114 115The `loader/generated` directory contains source code that is created by several 116generator scripts in the `scripts` directory. All changes to these scripts _must_ be submitted with the 117corresponding generated output to keep the repository self-consistent. This requirement is enforced by both 118GitHub actions. Regenerate source files after modifying any of the generator scripts and before building 119and testing your changes. More details can be found in [BUILD.md](BUILD.md#generated-source-code). 120 121#### Testing Your Changes 122 123* In order to run tests, you must first build the loader with testing enabled (see details 124 in the BUILD.md file). 125* If your changes expose an issue not previously tested against, please also provide one or more 126 tests which show a failure for the issue before your changes but pass successfully with your changes. 127* Once built, simply change to the build folder, and type "ctest" 128 * This will run all tests the loader has defined at the time 129* Additionally, once your change has begun the process of reviewing in Github, 130 it may be processed through the CI system. 131 * This may show additional failures on other platforms, so watch and be prepared to fix any 132 additional issues. 133 134#### Coding Conventions for [CMake](http://cmake.org) files 135 136* When editing configuration files for CMake, follow the style conventions of the surrounding code. 137 * The column limit is 132. 138 * The indent is 4 spaces. 139 * CMake functions are lower-case. 140 * Variable and keyword names are upper-case. 141 142### Contributor License Agreement (CLA) 143 144You will be prompted with a one-time "click-through" CLA dialog as part of 145submitting your pull request or other contribution to GitHub. 146 147### License and Copyrights 148 149All contributions made to the Vulkan-Loader repository are Khronos branded 150and as such, any new files need to have the Khronos license 151(Apache 2.0 style) and copyright included. 152Please see an existing file in this repository for an example. 153 154All contributions made to the LunarG repositories are to be made under 155the Apache 2.0 license and any new files need to include this license 156and any applicable copyrights. 157 158You can include your individual copyright after any existing copyrights. 159