103 lines
4.7 KiB
Plaintext
103 lines
4.7 KiB
Plaintext
= SonarSource Rule Specification repository
|
|
|
|
This repository contains the specification of every static analysis rule available in SonarLint, SonarCloud and SonarQube.
|
|
|
|
It also contains rules which have been dropped and rules which will one day be implemented.
|
|
|
|
WARNING: **Beta status**:
|
|
This repository is not used yet in production. The current source of truth remains the https://jira.sonarsource.com/issues/?jql=project%20%3D%20RSPEC[Rule Respository project in Jira]. **Don't create rules in this repository for now**. See <<beta,the "During the Beta" section>> for more information.
|
|
|
|
|
|
== Rules directory structure
|
|
|
|
* https://github.com/SonarSource/rspec/tree/master/rules[rules] directory: contains every specified rule.
|
|
** `rules/Sxxxx`: contains every specification for rule `Sxxxx`.
|
|
*** `rules/Sxxxx/*.adoc`: Asciidoc files which can be shared/included by multiple languages.
|
|
*** `rules/Sxxxx//metadata.json`: rule metadata which are shared between rules. Each language can override fields in its own `metadata.json` file.
|
|
*** `rules/Sxxxx/[LANGUAGE]`: contains specifications specific to a given language. `[LANGUAGE]` can be `java`, `cfamily`, `python`...
|
|
**** `rules/Sxxxx/[LANGUAGE]/rule.adoc`: asciidoc file used to generate the rule description for programming language `[LANGUAGE]`. It can include parts from `*.adoc` files located in the parent directory.
|
|
**** `rules/Sxxxx/[LANGUAGE]/metadata.json`: metadatas for the specific language. Each key at the top will completely override the key of the `metadata.json` file of the parent directory.
|
|
|
|
== Search rules
|
|
|
|
Go to the https://sonarsource.github.io/rspec/#/[Search Page] to find rules which have already been merged in the Master branch.
|
|
|
|
Go the the Github Pull Request tab to find rules which have not been merged yet.
|
|
|
|
== Create or modify a rule
|
|
|
|
Jira currently contains both implemented and unimplemented rules. This is why the `rules` directory contains both too.
|
|
|
|
However one of the reasons we are migrating to a git repository is that we want to have a clean process and history for rule creation and modification. Thus every newly created rule should follow the this workflow:
|
|
|
|
=== 1. Create a Pull Request
|
|
|
|
==== For a new rule
|
|
* go to the https://github.com/SonarSource/rspec/actions/workflows/create_new_rspec.yml[Create new RSPEC] github action
|
|
* click on the grey _Run wokflow_ button.
|
|
* in the field _"Comma-separated list of targeted languages"_ write the list of languages you want to specify this rule for.
|
|
* click on the green _Run workflow_ button.
|
|
|
|
==== To modify an existing rule
|
|
Create the Pull Request manually
|
|
In the description add the following text:
|
|
```
|
|
MODIFIES RULE: Sxxxx
|
|
```
|
|
|
|
=== 2. Edit the pull request
|
|
|
|
You should see https://github.com/pulls/assigned[a new Pull request assigned to you]. It contains a scaffolding of files for the new rule. Feel free to modify it as you please.
|
|
|
|
=== 3. Ask for a review
|
|
|
|
Every new rule should be reviewed.
|
|
|
|
If it is a new rule, or if it requires the analyzer to change its implementation, do not merge the Pull Request yet.
|
|
|
|
If the change does not require an implementation, merge the Pull Request
|
|
|
|
=== 4. Create an implementation ticket
|
|
|
|
In your analyzer, create an implementation ticket and reference the Pull request as follow:
|
|
```
|
|
RSPEC PR: SonarSource/rspec#xxxx
|
|
```
|
|
|
|
In the Pull Request adding the rule specification add the following text referencing the implementation ticket.
|
|
```
|
|
IMPLEMENTATION TICKET: SonarSource/sonar-java#xxx
|
|
```
|
|
Replace the repository with the one you currently work on.
|
|
|
|
=== 5. Implement the rule
|
|
|
|
Implement the rule, update analyzer's metadata, and merge pull requests in both your analyzer and rspec repositories.
|
|
|
|
==== Generate/Update rule metadata for the analyzer
|
|
|
|
* Download the last version of https://github.com/SonarSource/sonar-rule-api[rule-api].
|
|
* call `gh_generate` if you are adding a rule, or `gh_update` if you just want the last specification version.
|
|
|
|
Example:
|
|
```sh
|
|
$ java -jar rule-api-1.24.3.jar gh_generate -rule S4328
|
|
# or
|
|
$ java -jar rule-api-1.24.3.jar gh_update
|
|
```
|
|
|
|
== During the Beta
|
|
[#beta]
|
|
A cron job currenlty imports rules from https://jira.sonarsource.com/issues/?jql=project%20%3D%20RSPEC[Jira] to this repository every night. You can edit rules in this repository just to test it, but real specification work should be done on Jira.
|
|
|
|
== Tooling
|
|
|
|
=== https://github.com/SonarSource/rspec/tree/master/rspec-tools[rspec-tools]
|
|
|
|
Python CLI tool enabling to add and validate rules. It is used by Github checks and Github actions.
|
|
For more information see the README file in the `rspec-tools` directory.
|
|
|
|
=== https://github.com/SonarSource/rspec/tree/master/frontend[frontend]
|
|
|
|
Github page which enables the search of rules.
|
|
For more information see the README file in the `frontend` directory. |