4.1 KiB
Contributing
Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
Contributions to this project are released to the public under the project's open source license.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Adding a new query
If you have an idea for a query that you would like to share with other CodeQL users, please open a pull request to add it to this repository. Follow the steps below to help other users understand what your query does, and to ensure that your query is consistent with the other CodeQL queries.
-
Consult the documentation for query writers
There is lots of useful documentation to help you write CodeQL queries, ranging from information about query file structure to language-specific tutorials. For more information on the documentation available, see Writing QL queries on help.semmle.com.
-
Format your code correctly
All of the standard CodeQL queries and libraries are uniformly formatted for clarity and consistency, so we strongly recommend that all contributions follow the same formatting guidelines. If you use the CodeQL extension for Visual Studio Code, you can auto-format your query in the QL editor. For more information, see the QL style guide.
-
Make sure your query has the correct metadata
Query metadata is used by Semmle's analysis to identify your query and make sure the query results are displayed properly. The most important metadata to include are the
@name,@description, and the@kind. Other metadata properties (@precision,@severity, and@tags) are usually added after the query has been reviewed by the maintainers. For more information on writing query metadata, see the Query metadata style guide. -
Make sure the
selectstatement is compatible with the query typeThe
selectstatement of your query must be compatible with the query type (determined by the@kindmetadata property) for alert or path results to be displayed correctly in LGTM and Visual Studio Code. For more information onselectstatement format, see Introduction to query files on help.semmle.com. -
Write a query help file
Query help files explain the purpose of your query to other users. Write your query help in a
.qhelpfile and save it in the same directory as your new query. For more information on writing query help, see the Query help style guide. -
Maintain backwards compatibility
The standard CodeQL libraries must evolve in a backwards compatible manner. If any backwards incompatible changes need to be made, the existing API must first be marked as deprecated. This is done by adding a deprecated annotation along with a QLDoc reference to the replacement API. Only after at least one full release cycle has elapsed may the old API be removed.
In addition to contributions to our standard queries and libraries, we also welcome contributions of a more experimental nature, which do not need to fulfill all the requirements listed above. See the guidelines for experimental queries and libraries for details.