Merge pull request #1599 from jf205/contributing-queries/sd-3476

docs: add more information about contributing queries to the public repo

CONTRIBUTING.md

@@ -1,10 +1,50 @@
 # Contributing to QL
 
-We welcome contributions to our standard library and standard checks, got an idea for a new check, or how to improve an existing query? Then please go ahead an open a Pull Request!
+We welcome contributions to our standard library and standard checks. Got an idea for a new check, or how to improve an existing query? Then please go ahead and open a pull request!
 
-Before we accept your pull request, we will require that you have agreed to our Contributor License Agreement, this is not something that you need to do before you submit your pull request, but until you've done so, we will be unable to accept your contribution.
+Before we accept your pull request, we require that you have agreed to our Contributor License Agreement, this is not something that you need to do before you submit your pull request, but until you've done so, we will be unable to accept your contribution.
 
-Please read our [QL Style Guide](docs/ql-style-guide.md) for information on how to format QL code in this repository.
+## Adding a new query
+
+If you have an idea for a query that you would like to share with other Semmle 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 Semmle queries.
+
+1. **Consult the QL documentation for query writers**
+
+   There is lots of useful documentation to help you write QL, ranging from information about query file structure to language-specific tutorials. For more information on the documentation available, see [Writing QL queries](https://help.semmle.com/QL/learn-ql/writing-queries/writing-queries.html) on [help.semmle.com](https://help.semmle.com).
+
+2. **Format your QL correctly**
+
+   All of Semmle's standard QL queries and libraries are uniformly formatted for clarity and consistency, so we strongly recommend that all QL contributions follow the same formatting guidelines. If you use QL for Eclipse, you can auto-format your query in the [QL editor](https://help.semmle.com/ql-for-eclipse/Content/WebHelp/ql-editor.html). For more information, see the [QL style guide](https://github.com/Semmle/ql/blob/master/docs/ql-style-guide.md).
+
+3. **Make sure your query has the correct metadata**
+
+   Query metadata is used by Semmle's analysis to idenitfy 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 Semmle staff.
+   For more information on writing query metadata, see the [Query metadata style guide](https://github.com/Semmle/ql/blob/master/docs/query-metadata-style-guide.md).
+
+4. **Make sure the `select` statement is compatible with the query type**
+
+   The `select` statement of your query must be compatible with the query type (determined by the `@kind` metadata property) for alert or path results to be displayed correctly in LGTM and QL for Eclipse.
+   For more information on `select` statement format, see [Introduction to query files](https://help.semmle.com/QL/learn-ql/writing-queries/introduction-to-queries.html#select-clause) on help.semmle.com.
+
+5. **Save your query in a `.ql` file in correct language directory in the this repository**
+
+   There are five language-specific directories in this repository:
+   
+     * C/C++: `ql/cpp/ql/src`
+     * C#: `ql/csharp/ql/src`
+     * Java: `ql/java/ql/src`
+     * JavaScript: `ql/javascript/ql/src`
+     * Python: `ql/python/ql/src`
+
+   Each language-specific directory contains further subdirectories that group queries based on their `@tags` properties or purpose. Select the appropriate subdirectory for your new query, or create a new one if necessary. 
+
+6. **Write a query help file**
+
+   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 new query. 
+   For more information on writing query help, see the [Query help style guide](https://github.com/Semmle/ql/blob/master/docs/query-help-style-guide.md).
 
 ## Using your personal data
 

docs/ql-style-guide.md

@@ -2,7 +2,8 @@
 
 ## Introduction
 
-This document describes how to format the QL code you contribute to this repository. It covers aspects such as layout, white-space, naming and documentation. Adhering to consistent standards makes code easier to read and maintain. Of course, these are only guidelines, and can be overridden as the need arises on a case-by-case basis. Where existing code deviates from these guidelines, prefer consistency with the surrounding code.
+This document describes how to format the QL code you contribute to this repository. It covers aspects such as layout, white-space, naming, and documentation. Adhering to consistent standards makes code easier to read and maintain. Of course, these are only guidelines, and can be overridden as the need arises on a case-by-case basis. Where existing code deviates from these guidelines, prefer consistency with the surrounding code.
+Note, if you use QL for Eclipse, you can auto-format your query in the (QL editor)[https://help.semmle.com/ql-for-eclipse/Content/WebHelp/ql-editor.html].
 
 Words in *italic* are defined in the [Glossary](#glossary).
 

docs/query-metadata-style-guide.md

@@ -27,7 +27,7 @@ For examples of query files for the languages supported by Semmle, visit the fol
 
 ## Metadata area
 
-Query file metadata contains important information which defines the identifier and purpose of the query. The metadata is included as the content of a valid [QLDoc](https://help.semmle.com/QL/ql-spec/qldoc.html) comment, on lines with leading whitespace followed by `*`, between an initial `/**` and a trailing `*/`. For example:
+Query file metadata contains important information that defines the identifier and purpose of the query. The metadata is included as the content of a valid [QLDoc](https://help.semmle.com/QL/ql-spec/qldoc.html) comment, on lines with leading whitespace followed by `*`, between an initial `/**` and a trailing `*/`. For example:
 
 ```
 /**
@@ -43,7 +43,10 @@ Query file metadata contains important information which defines the identifier
  */
  ```
 
-In order to help others use your query, and to ensure that the query works correctly on LGTM, you should include all of the required information outlined below in the metadata, and as much of the optional information as possible. For further information on query metadata see [Query metadata](https://help.semmle.com/QL/learn-ql/ql/writing-queries/query-metadata.html) on help.semmle.com.
+To help others use your query, and to ensure that the query works correctly on LGTM, you should include all of the required information outlined below in the metadata, and as much of the optional information as possible. For further information on query metadata see [Query metadata](https://help.semmle.com/QL/learn-ql/ql/writing-queries/query-metadata.html) on help.semmle.com.
+
+
+
 
 ### Query name `@name`