From d7b1e84f485f440d26cfaef1b31eb1c280e9c0e8 Mon Sep 17 00:00:00 2001 From: Nicolas Harraudeau <40498978+nicolas-harraudeau-sonarsource@users.noreply.github.com> Date: Fri, 19 Feb 2021 09:06:56 +0100 Subject: [PATCH] Update main README --- README.adoc | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 20 ---------- 2 files changed, 103 insertions(+), 20 deletions(-) create mode 100644 README.adoc delete mode 100644 README.md diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000000..dab0570a5d --- /dev/null +++ b/README.adoc @@ -0,0 +1,103 @@ += 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 <> 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. \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index 99287c73b5..0000000000 --- a/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# rspec - - -Structure ---------- - -`rules` directory -- `RSPEC_****` directory for each rule - - a file per section shared between multiple languages: `main.adoc`, `compliant.adoc`, `noncompliant.adoc`, `exceptions.adoc`, `see.adoc` - - `metadata.json`: metadatas shared between laguage. They can be overridden. - - a directory per LANGUAGE: `java`, `c-family`, `python`... - - `rule.adoc`: root file used to generate the rule description for the specific language. It can include parts from `*.adoc` files defined in the parent directory. - - `metadata.json`: metadatas for the specific language. Each root key will completely override the key of the above `metadata.json` file. No "smart" merge takes place, which makes it easier to have in one glance the full value of a field. - - `compliant.py/java/...`, `noncompliant.py/java/...`: source code files containing compliant and noncompliant code examples. - -Metadata format ---------------- -The metadata match closely what plugins expect. -Additional fields: -* `qualityProfile`: quality profile(s) in which the rule should be registered. \ No newline at end of file