Update main README

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 <<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.

README.md

@@ -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.