mirror of
https://github.com/github/codeql.git
synced 2025-12-16 16:53:25 +01:00
Ruby: clean up docs
This commit is contained in:
Nick Rolfe
@@ -11,13 +11,14 @@ If you have an idea for a query that you would like to share with other CodeQL u
|
||||
|
||||
1. **Directory structure**
|
||||
|
||||
There are five language-specific query directories in this repository:
|
||||
There are six language-specific query directories in this repository:
|
||||
|
||||
* C/C++: `cpp/ql/src`
|
||||
* C#: `csharp/ql/src`
|
||||
* Java: `java/ql/src`
|
||||
* JavaScript: `javascript/ql/src`
|
||||
* Python: `python/ql/src`
|
||||
* Ruby: `ruby/ql/src`
|
||||
|
||||
Each language-specific directory contains further subdirectories that group queries based on their `@tags` or purpose.
|
||||
- Experimental queries and libraries are stored in the `experimental` subdirectory within each language-specific directory in the [CodeQL repository](https://github.com/github/codeql). For example, experimental Java queries and libraries are stored in `java/ql/src/experimental` and any corresponding tests in `java/ql/test/experimental`.
|
||||
|
||||
@@ -1,64 +0,0 @@
|
||||
## 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](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE).
|
||||
|
||||
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
|
||||
|
||||
## Building and testing
|
||||
|
||||
See [Developer information](docs/HOWTO.md) for information on building the Ruby extractor. There is no need to rebuild the extractor if you are only developing queries.
|
||||
|
||||
1. Install the CodeQL CLI as described in [Getting started with the CodeQL CLI](https://codeql.github.com/docs/codeql-cli/getting-started-with-the-codeql-cli/).
|
||||
|
||||
2. Ensure that `<extraction-root>/codeql` is in your `PATH`.
|
||||
|
||||
3. Clone this repository into `<extraction-root>/codeql-ruby` and change to this directory.
|
||||
|
||||
4. To run all tests in a directory and its subdirectories, run `codeql test run <directory>`, for example `codeql test run ql/test/query-tests/security`.
|
||||
|
||||
6. To run an individual test, run `codeql test run <filename>`, where `<filename>` is a `.ql` or `.qlref` file, for example `codeql test run ql/test/query-tests/security/cwe-078/CommandInjection.qlref`.
|
||||
|
||||
## 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.
|
||||
|
||||
1. **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 CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/) and the [CodeQL documentation](https://codeql.github.com/docs).
|
||||
|
||||
2. **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 using the [Format Document command](https://code.visualstudio.com/docs/editor/codebasics#_formatting). For more information, see the [QL style guide](https://github.com/github/codeql/blob/main/docs/ql-style-guide.md).
|
||||
|
||||
3. **Make sure your query has the correct metadata**
|
||||
|
||||
Query metadata is used 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](https://github.com/github/codeql/blob/main/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 Visual Studio Code.
|
||||
For more information on `select` statement format, see [About CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/about-codeql-queries/#select-clause) on the [CodeQL documentation](https://codeql.github.com/docs) site.
|
||||
|
||||
5. **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/github/codeql/blob/main/docs/query-help-style-guide.md).
|
||||
|
||||
6. **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](ql/docs/experimental.md) for details.
|
||||
|
||||
## Resources
|
||||
|
||||
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
|
||||
- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
|
||||
- [GitHub Help](https://help.github.com)
|
||||
- [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
|
||||
@@ -1,50 +1,14 @@
|
||||
# Ruby analysis support for CodeQL
|
||||
|
||||
This open-source repository contains the extractor, CodeQL libraries, and queries that power Ruby
|
||||
This directory contains the extractor, CodeQL libraries, and queries that power Ruby
|
||||
support in [LGTM](https://lgtm.com) and the other CodeQL products that [GitHub](https://github.com)
|
||||
makes available to its customers worldwide.
|
||||
|
||||
It contains two major components:
|
||||
- an extractor, written in Rust, that parses Ruby source code and converts it into a database
|
||||
that can be queried using CodeQL.
|
||||
- static analysis libraries and queries written in [CodeQL](https://codeql.github.com/docs/) that can be
|
||||
used to analyze such a database to find coding mistakes or security vulnerabilities.
|
||||
|
||||
The goal of this project is to provide comprehensive static analysis support for Ruby in CodeQL.
|
||||
|
||||
For the queries and libraries that power CodeQL support for other languages, visit [the CodeQL
|
||||
repository](https://github.com/github/codeql).
|
||||
|
||||
## Installation
|
||||
|
||||
Simply clone this repository. There are no external dependencies.
|
||||
|
||||
If you want to use the CodeQL extension for Visual Studio Code, import this repository into your VS
|
||||
Code workspace.
|
||||
|
||||
## Usage
|
||||
|
||||
To analyze a Ruby codebase, either use the [CodeQL command-line
|
||||
interface](https://codeql.github.com/docs/codeql-cli/) to create a database yourself, or
|
||||
download a pre-built database from [LGTM.com](https://lgtm.com/). You can then run any of the
|
||||
queries contained in this repository either on the command line or using the VS Code extension.
|
||||
|
||||
Note that the [lgtm.com](https://github.com/github/codeql-ruby/tree/lgtm.com) branch of this
|
||||
repository corresponds to the version of the queries that is currently deployed on LGTM.com.
|
||||
The [main](https://github.com/github/codeql-ruby/tree/main) branch may contain changes that
|
||||
have not been deployed yet, so you may need to upgrade databases downloaded from [LGTM.com](https://lgtm.com) before
|
||||
running queries on them.
|
||||
|
||||
## Contributions
|
||||
|
||||
Contributions are welcome! Please see our [contribution guidelines](CONTRIBUTING.md) and our
|
||||
[code of conduct](CODE_OF_CONDUCT.md) for details on how to participate in our community.
|
||||
|
||||
## Licensing
|
||||
|
||||
The code in this repository is licensed under the [MIT license](LICENSE).
|
||||
|
||||
## Resources
|
||||
|
||||
- [Writing CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/)
|
||||
- [CodeQL documentation](https://codeql.github.com/docs/)
|
||||
1. static analysis libraries and queries written in
|
||||
[CodeQL](https://codeql.github.com/docs/) that can be used to analyze such
|
||||
a database to find coding mistakes or security vulnerabilities.
|
||||
2. an extractor, written in Rust, that parses Ruby source code and converts it
|
||||
into a database that can be queried using CodeQL. See [Developer
|
||||
information](doc/HOWTO.md) for information on building the extractor (you
|
||||
do not need to do this if you are only developing queries).
|
||||
Reference in New Issue
Block a user