aboutsummaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorDave Houlton <daveh@lunarg.com>2018-06-21 10:24:43 -0600
committerDave Houlton <daveh@lunarg.com>2018-06-22 10:39:44 -0600
commitea2e5118b7d6dfb817aef00952a9f81445b0acb5 (patch)
treed45455bb9f4095b260b9368e303292c95eb8d359 /CONTRIBUTING.md
parentcacef47384a84d2410a68393c3abcb024e0692db (diff)
downloadvulkan-validation-layers-ea2e5118b7d6dfb817aef00952a9f81445b0acb5.tar.gz
scripts: Update contributing.md
Update Contributing.md to remove references to error database file and replace with instructions on using vk_validation_stats script. Change-Id: I8f9696cb1e03e8123887cdb5090a5c9dc93b2af8
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md21
1 files changed, 13 insertions, 8 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 07eaf8274..991dfe0f3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,9 +16,11 @@ and tests for these validation checks.
There are a couple of methods to identify areas of need:
* Examine the [issues list](https://github.com/KhronosGroup/Vulkan-ValidationLayers/issues)
in this repository and look for issues that are of interest
-* Alternatively, examine the [vk_validation_error_database.txt](layers/vk_validation_error_database.txt)
-file -- unimplemented validation checks are marked with an 'N' in the 'check_implemented' column and each
-of these needs coverage in the validation layers.
+* Alternatively, run the `vk_validation_stats.py` script (in the scripts directory) with the `-todo`
+command line argument to see a list of as-yet unimplemented validation checks.
+* Having selected a validation check to work on, it is often efficient to implement a block of related checks
+at once. Refer to the validation database output from `vk_validation_stats.py` (available in text, html,
+or csv format) to identify related checks that may be implemented simultaneously.
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
@@ -110,21 +112,24 @@ Pull Requests to GitHub are tested in the cloud on Linux and Windows VMs. The Li
The Linux testing includes iterating on all of the validation layer tests over multiple [different device](https://github.com/KhronosGroup/Vulkan-ValidationLayers/tree/master/tests/device_profiles) profiles using the [devsim layer](https://github.com/LunarG/VulkanTools/tree/master/layersvt) in combination with the [mock icd](https://github.com/KhronosGroup/Vulkan-Tools/tree/master/icd). This is a fast way to simulate testing across different devices. Any new tests must pass across all device profiles.
#### **Special Considerations for Validation Layers**
-* **Validation Tests** 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"
if the report is received. Otherwise, the test should indicate "failure".
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
+at the same time as the new validation check itself. 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.
-* **Validation Error/Warning Messages** Strive to give specific information describing the particulars of the failure, including
+* **Validation Error/Warning Messages:** Strive to give specific information describing the particulars of the failure, including
output all of the applicable Vulkan Objects and related values. Also, ensure that when messages can give suggestions about _how_ to
fix the problem, they should do so to better assist the user.
+* **Validation Statistics:** The `vk_validation_stats.py` script (in the scripts directory) inspects the layer and test source files
+and reports a variety of statistics on validation completeness and correctness. Before submitting a change you should run this
+script with the consistency check (`-c`) argument to ensure that your changes have not introduced any inconsistencies in the code.
### **Contributor License Agreement (CLA)**