## How to Contribute to Vulkan Source Repositories
-### **The Repositories**
-
-The source code for various Vulkan components is distributed across several GitHub repositories.
-The repositories sponsored by Khronos and LunarG are described here.
-In general, the canonical Vulkan Loader and Validation Layers sources are in the Khronos repository,
-while the LunarG repositories host sources for additional tools and sample programs.
+### **The Repository**
+The source code for The Vulkan-LoaderAndValidationLayer components is sponsored by Khronos and LunarG.
* [Khronos Vulkan-LoaderAndValidationLayers](https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers)
-* [LunarG VulkanTools](https://github.com/LunarG/VulkanTools)
-* [LunarG VulkanSamples](https://github.com/LunarG/VulkanSamples)
-As a convenience, the contents of the Vulkan-LoaderAndValidationLayers repository are downstreamed into the VulkanTools and VulkanSamples repositories via a branch named `trunk`.
-This makes the VulkanTools and VulkanSamples easier to work with and avoids compatibility issues
-that might arise with Vulkan-LoaderAndValidationLayers components if they were obtained from a separate repository.
### **The Vulkan Ecosystem Needs Your Help**
and tests for these validation checks.
If you desire to help in this area, please examine the
[issues list](https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/issues)
-in this repository and look for any unassigned issues that are of interest to you.
+in this repository and look for any issues that are of interest to you.
Of course, if you have your own work in mind, please open an issue to describe it and assign it to yourself.
Finally, please feel free to contact any of the developers that are actively contributing should you
wish to coordinate further.
Repository Issue labels:
-* _Incomplete_: These issues refer to missing validation checks that users have encountered during application development that would have been directly useful, and are high priority.
-* _Enhancement_: These issues refer to ideas for extending or improving the loader, demos, or validation layers.
* _Bug_: These issues refer to invalid or broken functionality and are the highest priority.
+* _Incomplete_: These issues refer to missing validation checks that users have encountered during application
+development that would have been directly useful, and are high priority.
+* _Enhancement_: These issues refer to ideas for extending or improving the loader, demos, or validation layers.
-If you choose to work on an issue that is already assigned, simply coordinate with the current assignee.
+It is the mainainers goal for all issues to be assigned within one business day of their submission. If you choose
+to work on an issue that is assigned, simply coordinate with the current assignee.
### **How to Submit Fixes**
* Use the existing GitHub forking and pull request process.
This will involve [forking the repository](https://help.github.com/articles/fork-a-repo/),
creating a branch with your commits, and then [submitting a pull request](https://help.github.com/articles/using-pull-requests/).
+* Please read and adhere to the style and process [guidelines](#coding conventions and formatting) enumerated below.
* Please base your fixes on the master branch. SDK branches are generally not updated except for critical fixes needed to repair an SDK release.
-* Please include the GitHub Issue number near the beginning of the commit text if applicable.
- * Example: "layers: GH123, Fix missing init"
-* 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.
#### **Coding Conventions and Formatting**
* Use the **[Google style guide](https://google.github.io/styleguide/cppguide.html)** for source code with the following exceptions:
* The column limit is 132 (as opposed to the default value 80). The clang-format tool will handle this. See below.
* The indent is 4 spaces instead of the default 2 spaces. Again, the clang-format tool will handle this.
- * If you can justify a reason for violating a rule in the guidelines, then you are free to do so. Be prepared to defend your decision during code review. This should be used responsibly. An example of a bad reason is "I don't like that rule." An example of a good reason is "This violates the style guide, but it improves type safety."
+ * If you can justify a reason for violating a rule in the guidelines, then you are free to do so. Be prepared to defend your
+decision during code review. This should be used responsibly. An example of a bad reason is "I don't like that rule." An example of
+a good reason is "This violates the style guide, but it improves type safety."
-* Run **clang-format** on your changes to maintain formatting
- * There are `.clang-format files` throughout the repository to define clang-format settings
+* Run **clang-format** on your changes to maintain consistent formatting
+ * There are `.clang-format files` present in the repository to define clang-format settings
which are found and used automatically by clang-format.
* A sample git workflow may look like:
> $ git add -u .
> $ git commit
-* **Format your git commit messages** consistently with the repo
- * Limit the subject line to 50 characters. Begin with a one-word component description followed by a colon (e.g. loader, layers, tests, etc.).
- * Separate subject from body with a blank line.
- * Wrap the body at 72 characters.
- * Capitalize the subject line.
- * Do not end the subject line with a period.
- * Use the body to explain what and why vs. how.
- * Use the imperative mood in the subject line. This just means to write it as a command (e.g. Fix the sprocket).
+* **Commit Messages**
+ * Limit the subject line to 50 characters -- this allows the information to display correctly in git/Github logs
+ * Begin subject line with a one-word component description followed by a colon (e.g. loader, layers, tests, etc.)
+ * Separate subject from body with a blank line
+ * Wrap the body at 72 characters
+ * Capitalize the subject line
+ * Do not end the subject line with a period
+ * Use the body to explain what and why vs. how
+ * Use the imperative mode in the subject line. This just means to write it as a command (e.g. Fix the sprocket)
+
+Strive for commits that implement a single or related set of functionality, using as many commits as is necessary (more is better).
+That said, please ensure that the repository compiles and passes tests without error for each commit in your pull request. Note
+that to be accepted into the repository, the pull request must [pass all tests](#testing your changes) on all supported platforms
+-- the automatic Github Travis and AppVeyor continuous integration features will assist in enforcing this requirement.
#### **Testing Your Changes**
* Run the existing tests in the repository before and after each if your commits to check for any regressions.
> run_all_tests.sh
-* On Windows, a quick sanity check can be run from inside Visual Studio -- just run the `vk_layer_validation_tests` project, or you can run `run_all_tests.ps1` from a PowerShell window
+* On Windows, a quick sanity check can be run from inside Visual Studio -- just run the `vk_layer_validation_tests` project,
+or you can run `run_all_tests.ps1` from a PowerShell window
* Note that some tests may fail with known issues or driver-specific problems.
The idea here is that your changes shouldn't change the test results, unless that was the intent of your changes.
* Run tests that explicitly exercise your changes.
* Feel free to subject your code changes to other tests as well!
+
#### **Special Considerations for Validation Layers**
-If you are submitting a change that adds a new validation check, you should also construct a "negative" test function.
+* **Validation Tests** If you are submitting a change that adds a new validation check, you should also construct a "negative" test function.
The negative test function purposely violates the validation rule that the new validation check is looking for.
The test should cause your new validation check to identify the violation and issue a validation error report.
And finally, the test should check that the validation error report is generated and consider the test as "passing"
This new test should be added to the validation layer test program in the `tests` directory and contributed
at the same time as the new validation check itself, along with appropriate updates to `layers\vk_validation_error_database.txt`.
There are many existing validation tests in this directory that can be used as a starting point.
+* **Validation Checks** The majority of validation checks are carried out by the Core Validation layer. In general, this layer
+contains checks that require some amount of application state to carry out. In contrast, the parameter validation layer contains
+checks that require (mostly) no state at all. Please inquire if you are unsure of the location for your contribution. The other
+layers (threading, object_tracker, unique_objects) are more special-purpose and are mostly code-generated from the specification.
### **Contributor License Agreement (CLA)**
--- /dev/null
+## Vulkan Loader and Validation Layers Repository Management
+
+# **Open Source Project \96 Objectives**
+
+* Alignment with the Vulkan Specification
+ - The goal is for validation layer behavior to enforce the vulkan specification on applications. Questions on specification
+interpretations may require consulting with the Khronos Vulkan Workgroup for resolution
+ - [Core Specification](https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.html)
+ - [Header Files](https://www.khronos.org/registry/vulkan/#headers)
+ - [SDK Resources](https://vulkan.lunarg.com)
+* ISV Enablement
+ - Updates of loader and validation layer functionality should be available in a timely fashion
+ - All new specification features should have validation at public launch
+ - Every effort will be made to be responsive to ISV issues with validation layers
+* Cross Platform Compatibility
+ - Google and LunarG collaboration:
+ - Google: Monitor for Android
+ - LunarG: Monitor for desktop (Windows and Linux)
+ - Continuous Integration: Internal HW test farms monitor various hardware/software platforms
+* Repo Quality
+ - Repo remains in healthy state with all tests passing and good-quality, consistent codebase
+ - Continuous Integration: Along with Github, internal test farms perform pre-commit cloud testing on pull-requests
+
+# **Roles and Definitions**
+* Contributor, Commenter, User
+ - Submitting contributions, issues, or users of the repository
+* Approver
+ - Experienced project members who have made significant technical contributions
+ - Write control: Approve pull/merge requests (verify submissions vs. accepance criteria)
+* Technical Project Leads
+ - Lead the project in terms of versioning, quality assurance, and overarching objectives
+ - Monitor github issues and drive timely resolution
+ - Designate new approvers
+ - Ensure project information such as the Readme, Contributing docs, wiki, etc., kept up-to-date
+ - Act as a facilitator in resolving technical conflicts
+ - Is a point-of-contact for project-related questions
+
+The technical project leads for this repository are:
+* **Mark Lobodzinski** [mark@lunarg.com](mailto:mark@lunarg.com)
+* **Tobin Ehlis** [tobine@google.com](mailto:tobine@google.com)
+
+# **Acceptance Criteria and Process**
+ - All source code to include Khronos copyright and license (Apache 2.0).
+ - Additional copyrights of contributors appended
+ - Contributions are via pull requests
+ - Project leads will assigning approvers to contributor pull requests
+ - Approvers can self-assign their reviewers
+ - For complex or invasive contributions, Project Leads may request approval from specific reviewers
+ - At least one review approval is required to complete a pull request
+ - The goal is to be responsive to contributors while ensuring acceptance criteria is met and to facilitate their submissions
+ - Approval is dependent upon adherence to the guidelines in [CONTRIBUTING.md](CONTRIBUTING.md), and alignment with
+repository goals of maintainability, completeness, and quality
+ - Conflicts or questions will ultimately be resolved by the project leads
# Vulkan Ecosystem Components
-This project provides Khronos official ICD loader and validation layers for Vulkan developers on Windows and Linux.
+This project provides the Khronos official ICD loader and validation layers for Vulkan developers on Windows and Linux.
## CI Build Status
| Platform | Build Status |
## Introduction
-Vulkan is an Explicit API, enabling direct control over how GPUs actually work. No (or very little) validation
-or error checking is done inside a Vulkan driver. Applications have full control and responsibility. Any errors in
-how Vulkan is used often result in a crash. This project provides standard validation layers that can be enabled
-to ease development by helping developers verify their applications correctly use the Vulkan API.
+Vulkan is an Explicit API, enabling direct control over how GPUs actually work. By design, minimal error checking is done inside
+a Vulkan driver. Applications have full control and responsibility for correct operation. Any errors in
+how Vulkan is used can result in a crash. This project provides Vulkan validation layers that can be enabled
+to assist development by enabling developers to verify their applications correct use of the Vulkan API.
Vulkan supports multiple GPUs and multiple global contexts (VkInstance). The ICD loader is necessary to
-support multiple GPUs and the VkInstance level Vulkan commands. Additionally, the loader manages inserting
-Vulkan layer libraries, including validation layers between the application and the ICD.
+support multiple GPUs and VkInstance-level Vulkan commands. Additionally, the loader manages inserting
+Vulkan layer libraries such as validation layers between the application and the ICD.
The following components are available in this repository:
-- Vulkan header files
+- [Vulkan header files](include/vulkan/)
- [*ICD Loader*](loader/)
- [*Validation Layers*](layers/)
- [*Mock ICD*](icd/)
-- Demos and tests for the loader and validation layers
+- [*Demos*](demos/)
+- [*Tests*](tests/)
-## Contributing
+## Contact Information
+[Tobine Ehlis](mailto:tobine@google.com)
+[Mark Lobodzinski](mailto:mark@lunarg.com)
-If you intend to contribute, the preferred work flow is for you to develop your contribution
-in a fork of this repo in your GitHub account and then submit a pull request.
-Please see the [CONTRIBUTING](CONTRIBUTING.md) file in this repository for more details
+## Information for Developing or Contributing:
+
+Please see the [CONTRIBUTING](CONTRIBUTING.md) file in this repository for more details.
+Please see the [GOVERNANCE](GOVERNANCE.md) file in this repository for repository management details.
## How to Build and Run
[BUILD.md](BUILD.md)
-includes directions for building all the components, running the validation tests and running the demo applications.
+Includes directions for building all components as well as running validation tests and demo applications.
Information on how to enable the various Validation layers is in
[layers/README.md](layers/README.md).
Architecture and interface information for the loader is in
[loader/LoaderAndLayerInterface.md](loader/LoaderAndLayerInterface.md).
-#### **NOTE**: Update Nvidia Drivers
-- A recent glslang change exposed a bug in the texel fetch behavior on Nvidia devices under certain situations.
-- Previously, we reverted the glslang change which exposed it.
-- Nvidia has since resolved the issue, and we are now removing the workaround.
-- Driver installs with the fix are available on their download page, just look for:
- - Linux Drivers starting with version 367.35
- - Windows Drivers starting at version 372.54
-
## License
This work is released as open source under a Apache-style license from Khronos including a Khronos copyright.
See COPYRIGHT.txt for a full list of licenses used in this repository.
## Acknowledgements
-While this project has been developed primarily by LunarG, Inc; there are many other
+While this project has been developed primarily by LunarG, Inc., there are many other
companies and individuals making this possible: Valve Corporation, funding
project development; Google providing significant contributions to the validation layers;
Khronos providing oversight and hosting of the project.
-
-
projects / platform / upstream / Vulkan-Tools.git / commitdiff