ishangsf/rspec
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add the flow-charts and remarks to the documentation. (#43)

Browse Source
This commit is contained in:
Arseniy Zaostrovnykh 2021-02-19 16:54:29 +01:00 committed by GitHub
parent cbfaec24af
commit 0481d4ff7d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 58 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
README.adoc
View File

@ -1,73 +1,76 @@
ifdef::env-github[]
:warning-caption: :warning:
:note-caption: :information_source:
endif::[]
= SonarSource Rule Specification repository
This repository contains the specification of every static analysis rule available in SonarLint, SonarCloud and SonarQube.
This repository contains the specification of every static-analysis rule available in SonarLint, SonarCloud, or 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.
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]. **Do not 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/*.adoc`: Asciidoc files which can be reused by multiple language-specific descriptions.
*** `rules/Sxxxx/metadata.json`: rule metadata shared between language-specific RSPECs. Each language can override fields in its own `metadata.json` file.
*** `rules/Sxxxx/[LANGUAGE]`: contains the language-specific RSPEC. `[LANGUAGE]` can be `java`, `cfamily`, `python`...
**** `rules/Sxxxx/[LANGUAGE]/rule.adoc`: asciidoc file used to generate the `Sxxxx` 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 to the https://sonarsource.github.io/rspec/#/[Search Page] to find the rules that have already been merged in the `master` branch.
Go the the Github Pull Request tab to find rules which have not been merged yet.
Go the the GitHub https://github.com/SonarSource/rspec/pulls[pull-request] tab to find the rules that 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:
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 this workflow:
=== 1. Create a Pull Request
=== 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
* 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:
```
Create a pull request manually
In the subject 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.
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 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
If the change does not require an implementation, merge the pull request after the review.
=== 4. Create an implementation ticket
In your analyzer, create an implementation ticket and reference the Pull request as follow:
```
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.
```
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
@ -80,24 +83,43 @@ Implement the rule, update analyzer's metadata, and merge pull requests in both
* call `gh_generate` if you are adding a rule, or `gh_update` if you just want the last specification version.
Example:
```sh
[source,shell]
----
$ java -jar rule-api-1.24.3.jar gh_generate -rule S4328
# or
$ java -jar rule-api-1.24.3.jar gh_update
```
----
NOTE: If you generate rules in an empty directory,
you have to run `gh_update` immediately after,
because rule-api relies on the files in the directory to determine the covered set of rules
when generating the deprecation notes for superseded rules.
== 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.
A https://en.wikipedia.org/wiki/Cron[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 in Jira.
WARNING: On top of the Jira Markdown pitfalls, the conversion script tends to break on specific syntax. Please see https://docs.google.com/document/d/1kseOIF8fVKTwg0v5-pw7GZYUg15uY8XHM3augh5OoUA/edit[Jira markdown quirks] for the list of known issues to avoid in your RSPECs.
== 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.
https://github.com/SonarSource/rspec/tree/master/rspec-tools[rspec-tools]::
A python CLI tool for adding and validating 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.
https://github.com/SonarSource/rspec/tree/master/frontend[frontend]::
The GitHub page that enables the search for rules.
For more information see the README file in the `frontend` directory.
== RSPEC dataflow
Current path of an RSPEC from its inception in Jira RSPEC project to its consumption in SQ/SC/SL or on rules.sonarsource.com:
image::img/RSPEC-flow-1.png[]
Here the github flow is grayed out, because it is rudimentary and exists solely for the beta-testing purpose.
However, once the beta-testing period is over, the flow will look differently:
image::img/RSPEC-flow-2.png[]
Here Jira RSPEC project becomes read-only, and the github repository becomes the source of truth.
Once Jira RSPEC is frozen, the export script becomes unncessary and will be stopped.
The https://sonarsource.github.io/rspec/#/[search page] taps directly into the GitHub repository and indexes the rules to
replace the powerful search from the now-obsolete Jira database.

BIN
img/RSPEC-flow-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
img/RSPEC-flow-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

1
img/RSPEC-flow.drawio Normal file
View File

@ -0,0 +1 @@
<mxfile modified="2021-02-19T15:04:41.376Z" host="app.diagrams.net" agent="5.0 (X11)" etag="Y9FQjmlkbswknfFz2YXr" version="14.4.2" type="device"><diagram id="C2fSY1v2SiZeoUbDoYyL" name="Page-1">3VrZcpswFP0aPybDTvzoOk4ymaST1p2m6ZsCCiiVERUitvP1lUCYRbaD4wXXw4PR1YbOOffqItwzh5PZNQVxeE98iHuG5s965mXPMPS+Y/EfYZnnFtc2c0NAkS8blYYxeofSqElrinyY1BoyQjBDcd3okSiCHqvZAKVkWm/2QnB91hgEUDGMPYBV6yPyWSitutMvK24gCkI59YXh5hUTUDSWK0lC4JNpxWSOeuaQEsLyu8lsCLEAr8Al73e1onbxYBRGrE0HYzr58fvx4dGa9p2fTvT17/3r7ZluyIdj82LF0OcAyCKhLCQBiQAeldYvlKSRD8WwGi+Vbe4IiblR58ZXyNhcsglSRrgpZBMsa+EMsV+i+7ktS0+VmsuZHDkrzItCxOi80kkUn6p1ZbesVPTL1ycWtRI3aUpISj24DiypP0ADyNa0sxfscreAZAL58/B+FGLA0Fv9OYDUZ7BoV1LIbySLmzCaj/sGcCpnukUUcMv38cNoqLBdcingn4aIwXEMMhim3KPrvMmhIWVwth5NdfXS/y3pDdOKMxW2sOJHjrYvfJwuFa9X9F6qf7nid6hco6VyzU6V6/4vzJSxqBaJysC0/1jUllGrS0YN83h2F60lo53tLm0ZXRFfWzOadR1QCuaVBjFBEUsqIz8IA28g47xpyngsw3gz12g0d9e15jf59KWwFuvYQmv28Wjtc5mM/oHWXkjEhgQTmq3OdLKL2xNGyR9YqdGyi9f4IAkXe3sHUt02EdqNVK3NtGodQqxKktYzHMwEZeiN3wbidsCFOH+HNCnq+FSV6u5SOdmhiZyuLcntjEPmdqYC6/gbH2gsRhvfdQ6Y5dQBW5YL24fEy2ojQ5pimJwnPCzSPDCce2RypJJsIqw7XUOsd5oCHSKpPZ5tyW65LRmd5sT9bvMU9zOJymaKqPG7WgZN4YzE1ZEi3C4lYSth+Bqxm/S5PLThDxKT7aLr5m66TTxeF38Pe9yj7nFwFnMPElB6FMVMgZUvl9Wxq2MUkUj45AvCuGECGAURL3ocHsjtXwR4yAN4ICsmyPczh15GVt3Jd5GgNTZDQyVjGRfGvrgoVlDhQiQXZyBGp0vCIt1Yw8KyjGR/LKgvHzzMQZDA0yXBMvU6CfpFxySoYSmNfcA4B5pH+Fr56g0NgyhIQQCT02VGd5fsEM5BqXB2TcWeUV+1k++SjeIwRO+aHV1XAD+x96fe7tLdth8ou30BchV/qx4uBIiF6fM54unuFU1i6InZxIeEK0UIG+W/Sp57MRDXh+8h22VgzbNIW/UnQ9tNPizwWvyZID+oLP+SYY7+AQ==</diagram></mxfile>