Merge pull request #5114 from geoffw0/codeqltestdoc

MathiasVP · web-flow · commit 88263cb89e1b · 2021-02-18T10:43:17.000+01:00
Documentation: Make our policy for copied example code clear and visible.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -49,7 +49,11 @@ If you have an idea for a query that you would like to share with other CodeQL u
 
     - The query must have at least one true positive result on some revision of a real project.
 
-Experimental queries and libraries may not be actively maintained as the [supported](docs/supported-queries.md) libraries evolve. They may also be changed in backwards-incompatible ways or may be removed entirely in the future without deprecation warnings.
+6. **Query help files and unit tests**
+
+	- Query help (`.qhelp`) files and unit tests are optional (but strongly encouraged!) for queries in the `experimental` directories. For more information about contributing query help files and unit tests, see [Supported CodeQL queries and libraries](docs/supported-queries.md).
+
+Experimental queries and libraries may not be actively maintained as the supported libraries evolve. They may also be changed in backwards-incompatible ways or may be removed entirely in the future without deprecation warnings.
 
 After the experimental query is merged, we welcome pull requests to improve it. Before a query can be moved out of the `experimental` subdirectory, it must satisfy [the requirements for being a supported query](docs/supported-queries.md).
 
diff --git a/cpp/ql/test/README.md b/cpp/ql/test/README.md
@@ -1,6 +1,6 @@
 # C/C++ CodeQL tests
 
-This document provides additional information about the C/C++ CodeQL Tests located in `cpp/ql/test`.  See [Contributing to CodeQL](/CONTRIBUTING.md) for general information about contributing to this repository.
+This document provides additional information about the C/C++ CodeQL tests located in `cpp/ql/test`.  The principles under "Copying code", below, also apply to any other C/C++ code in this repository, such as examples linked from query `.qhelp` files in `cpp/ql/src`.  For more general information about contributing to this repository, see [Contributing to CodeQL](/CONTRIBUTING.md).
 
 The tests can be run through Visual Studio Code.  Advanced users may also use the `codeql test run` command.
 
diff --git a/docs/supported-queries.md b/docs/supported-queries.md
@@ -20,14 +20,15 @@ The process must begin with the first step and must conclude with the final step
 
    Query help files explain the purpose of your query to other users. Write your query help in a `.qhelp` file and save it in the same directory as your query. For more information on writing query help, see the [Query help style guide](query-help-style-guide.md).
 
-   - Note, in particular, that almost all queries need to have a pair of "before" and "after" examples demonstrating the kind of problem the query identifies and how to fix it. Make sure that the examples are actually consistent with what the query does, for example by including them in your unit tests.
+   - Note, in particular, that almost all queries need to have a pair of "before" and "after" examples demonstrating the kind of problem the query identifies and how to fix it. Make sure that the examples are actually consistent with what the query does, for example by including them in your unit tests. Examples must be original, not copied from third-party sources.
    - At the time of writing, there is no way of previewing help locally. Once you've opened a PR, a preview will be created as part of the CI checks. A GitHub employee will review this and let you know of any problems.
 
 3. **Write unit tests**
 
    Add one or more unit tests for the query (and for any library changes you make) to the `ql/<language>/ql/test/experimental` directory. Tests for library changes go into the `library-tests` subdirectory, and tests for queries go into `query-tests` with their relative path mirroring the query's location under `ql/<language>/ql/src/experimental`.
 
-   See the section on [Testing custom queries](https://help.semmle.com/codeql/codeql-cli/procedures/test-queries.html) in the [CodeQL documentation](https://help.semmle.com/codeql/) for more information.
+ 	- See the section on [Testing custom queries](https://help.semmle.com/codeql/codeql-cli/procedures/test-queries.html) in the [CodeQL documentation](https://help.semmle.com/codeql/) for more information.
+	- See [C/C++ CodeQL tests](/cpp/ql/test/README.md) for more information about contributing tests for C/C++ queries in particular.
 
 4. **Test for correctness on real-world code**
 
