diff --git a/README.adoc b/README.adoc index 9bd22684db..4477f32398 100644 --- a/README.adoc +++ b/README.adoc @@ -8,9 +8,6 @@ This repository contains the specification of every static-analysis rule availab 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]. **Do not 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. @@ -18,38 +15,85 @@ WARNING: **Beta status**: This repository is not used yet in production. The cur *** `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. For every rule, there must be at least one `[LANGUAGE]` subdirectory. + -`[LANGUAGE]` can be any of the following: +`[LANGUAGE]` can be any of the following: include::supported_languages.adoc[] **** `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 the rules that have already been merged in the `master` branch. +All specified rules (implemented or not) are listed in the https://sonarsource.github.io/rspec/#/[Search Page]. + +For each rule, you can find the languages it covers, the descriptions for each language as well as the related open tickets and pull requests. + +There will be a red warning with a link to the rule pull request if the rule has not been implemented yet (i.e. is not present on the main branch yet). -Go the the GitHub https://github.com/SonarSource/rspec/pulls[pull-request] tab to find the rules that have not been merged yet. You can use the "Search in unimplemented" link on the Search Page to repeat your search in the PRs. WARNING: Unlike the Search Page, the GitHub search across the PRs for unimplemented rules considers only the PR summary and title. It does not search the content of the proposed rule (i.e. it does not look into `rule.adoc` nor into `metadata.json`). == Create or modify a rule -Jira currently contains both implemented and unimplemented rules. This is why the `rules` directory contains both too. +Before, the Languages Team used Jira to host 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 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 or modification of rule should follow this workflow: === 1. Create a pull request -==== For a new rule -1. go to the https://github.com/SonarSource/rspec/actions/workflows/create_new_rspec.yml[Create new RSPEC] GitHub action -2. click on the grey _Run wokflow_ button (on the right). -3. in the field _"Comma-separated list of targeted languages"_ write the list of languages you want to specify this rule for. + -They can be any of the following: +==== To create 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 (on the right). +. in the field _"Comma-separated list of targeted languages"_ write the list of languages you want to specify this rule for. + +They can be any of the following: include::supported_languages.adoc[] -4. click on the green _Run workflow_ button. +. click on the green _Run workflow_ button. image::img/new-rule-workflow.png[] +You should see https://github.com/pulls/assigned[a new pull request assigned to you]. It might take up to a few minutes to appear. +It contains a scaffolding of files for the new rule. Feel free to modify it as you please. + +The title of the PR for a new rule will say only "Create rule Sxxxx", which is not very informative. + +Modify the title to better summarize the nature or the rule, so that it is easier to find when searching through unimplemented rules. +Do preserve the "Create rule Sxxxx" prefix, as it is used by our tooling. +For example: + +---- +Create rule S7028: All identifiers should be in CamelCase +---- + +Add the description of the PR to further increase its discoverability +(GitHub PR search does not see the `rule.adoc`). +To do that, click on the three dots (next to the smile) on the first comment (created by github-actions bot) and select "Edit". + +The rule must contain subdirectories corresponding to all the languages this rule will be implemented for (by the time the PR is merged). + +Each language subdirectory contains the `rule.adoc` that is the root document used to render the specification. +The rule specification in `rule.adoc` can include other `*.adoc` files that are in the language subdirectory or in the parent directory by using the `include::content.adoc[]` syntax. + +To reduce the number of turnarounds with the asciidoc edits you can install an asciidoc plugin. +Otherwise, you can use https://asciidoclive.com/[AsciiDocLIVE] and this https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[cheatsheet]. + +==== To add language to an existing rule + +If the rule exists on the main branch, create a PR named "Create rule Sxxxx[_language_]: _rule title_". For example: +---- +Create rule S100[java]: Method names should comply with a naming convention +---- + +Otherwise, if the rule has not been merged yet (i.e. the rule has not been implemented by any plugin), you can use the already existing PR corresponding to this rule. + + +Then, + +* Create a subdirectory with the name of the language you want to add. + +It can be any of the following: +include::supported_languages.adoc[] +* Add two files in this subdirectory: + +** `rule.adoc`: write down the whole description of the rule. If you want to include already existing parts (that are in the current or the parent directory), use the `include::` syntax. +** `metadata.json`: it automatically inherits from the `metadata.json` of the parent directory so you only need to write the parts that need to be overwritten. + +Please note that in any case this file should at least contain two curly braces (`{ }`) + + ==== To modify an existing rule Create a branch for your modifications manually. Then open a pull request manually. @@ -62,7 +106,6 @@ Add a short summary of the PR after the required prefix. For example: Modify rule S1234: Allow tail recursion for languages supporting TCO ---- - ==== To deprecate a rule Create a branch for the deprecation manually. Then open a pull request manually. @@ -80,57 +123,33 @@ In the `metadata.json` of the rule you want to deprecate: NOTE: use a GitHub hot-key `t` in the source view to navigate to an existing rule specification. -=== 2. Edit the pull request +=== 2. Ask for a review -You should see https://github.com/pulls/assigned[a new pull request assigned to you]. It might take up to a few minutes to appear. -It contains a scaffolding of files for the new rule. Feel free to modify it as you please. - -The title of the PR for a new rule will say only "Create rule Sxxxx", which is not very informative. - -Modify the title to better summarize the nature or the rule, so that it is easier to find when searching through unimplemented rules. -Do preserve the "Create rule Sxxxx" prefix, as it is used by our tooling. -For example: - ----- -Create rule S7028: All identifiers should be in CamelCase ----- - -Add the description of the PR to further increase its discoverability -(GitHub PR search does not see the `rule.adoc`). -To do that, click on the three dots (next to the smile) on the first comment (created by github-actions bot) and select "Edit". - -The rule must contain subdirectories corresponding to all the languages this rule is implemented for. - -Each language subdirectory contains the `rule.adoc` that is the root document used to render the specification. -The rule specification in `rule.adoc` can include other `*.adoc` files that are in the language subdirectory or in the parent directory by using the `include::content.adoc[]` syntax. - -To reduce the number of turnarounds with the asciidoc edits you can install an asciidoc plugin. -Otherwise, you can use https://asciidoclive.com/[AsciiDocLIVE] and this https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[cheatsheet]. - -=== 3. Ask for a review - -Every new rule should be reviewed. +Every PR that is creating or modifying a 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 after the review. -=== 4. Create an implementation ticket +=== 3. Create an implementation ticket -In your analyzer create an implementation ticket and reference the pull request as follow: +Create an implementation ticket as it is usually done for your plugin (i.e. as a Jira ticket or a Github issue). + +For this ticket to be correcty indexed on the search page of the rules, it has to contain the rule ID (RSPEC-1234 or S1234) either in the ticket title or in the ticket description. + +It is also recommended to add a link to the Github Page of the related rule, to ease the navigation between the ticket and the rule. + +In the pull request adding the rule specification, add the following text referencing the implementation ticket: ---- -RSPEC PR: SonarSource/rspec#xxxx +Implementation ticket: CPP-1234 (for a CFamily ticket on Jira) +---- +or +---- +Implementation ticket: SonarSource/sonar-dotnet/issues/1234 (for a sonar-dotnet issue on Github) ---- -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 +=== 4. Implement the rule -Implement the rule as usual. + +Implement the rule or the modification as usual. + Merge the RSPEC pull request before updating the metadata of the analyzer otherwise `rule-api` will not work. + And finally, merge the rule implementation in your analyzer repository. @@ -152,12 +171,6 @@ 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 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]:: A python CLI tool for adding and validating rules. It is used by GitHub checks and GitHub actions. @@ -167,16 +180,14 @@ 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: +The following graph shows the path of an RSPEC from its inception in Github RSPEC repository to its consumption in SQ/SC/SL or on rules.sonarsource.com: + +(The part that is grayed out corresponds to what existed before, when RSPECs were hosted in Jira) 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. +== Help + +Tickets related to this RSPEC repository are in Jira, in the https://jira.sonarsource.com/projects/RULEAPI/issues/RULEAPI-324?filter=allopenissues[RULEAPI] project. + +You found a bug, something is bothering you or you have an idea of how to improve the project? First, have a look at all the https://jira.sonarsource.com/projects/RULEAPI/issues/RULEAPI-324?filter=allopenissues[open tickets]. If you don't see anything related to your subject, please open a new ticket in the backlog, with `backlog` as the fix version. diff --git a/img/RSPEC-flow-1.drawio b/img/RSPEC-flow-1.drawio deleted file mode 100644 index 2c26ddff6c..0000000000 --- a/img/RSPEC-flow-1.drawio +++ /dev/null @@ -1 +0,0 @@ -3VrbcpswEP0aPybDzRA/Oo6TTCbppHWnafqmgAJKZUSF8CVfXwlkc7WLEwzUw0PQaiWhc452F+KBPpmvbigIvAfiQDzQFGc10K8GmqaOTIP/EZZ1YrGGemJwKXKkU2qYoXcojYq0RsiBYc6REYIZCvJGm/g+tFnOBigly7zbK8H5VQPgwpJhZgNctj4hh3nSqpqjtOMWIteTS19oVtIxBxtnuZPQAw5ZZkz6dKBPKCEsuZuvJhAL8Da4JOOud/RuH4xCn9UZoC3n3389PT4Zy5H5w/S//Hl4uztTNflwbL3ZMXQ4ALJJKPOIS3yAp6n1kpLId6CYVuGt1OeekIAbVW58g4ytJZsgYoSbPDbHsheuEPsphp8PZes503O1kjPHjfWm4TO6zgwSzedsXzosbm3GlWGSyIUkojbch42UG6AuZHv8homfwC2zgCThBpI55M/DHSjEgKFFXlhA6tPd+qUU8hvJ4iGMJvMuAI7kSneIAm75NnucTkpsp1wK+JceYnAWgBiXJT/Red52YrmAlMHV3t3L86/Jc7PMHCZDnhAvc45M5Vj4mF0qXs3oPVV/teI/rlytpnL1finX+l+YSWNRLhKlganxWFSXUaNXjGp6f7KLUpPRtrJLXUbVphmNh44pBeuMQ0CQz8LMzI/CwB1kUNd1GY9lGB/lS42Ct7XHmd8ki6ey2u7iE0ob9kdpH6tj1H8o7ZX4bEIwofHudDO+uD1klPyGmR4lvniPA0Jvm9mPL9TGy6BGhHqgVNsRa6lEG2gmZoIytOC3rrgdcyGu3yENN318qUx3d4Wc7C0id1FR2GltFnZ6CdXZVz7RTMw2u+8cL8MsKK0Cr2GbeBl1VEgjDMPzkEdFmgSKc5vMe6rIIsKq0TXEaqf1TxsVbWdZaVgzK2n9KohH3ZYp1kfqlMMUkeN3twyKwpmKqx1FWL0oVIxCOlD21ylFd7OFOmVYyhA3iN1GL+nHJI5RQD4X+GtHkIuxuJr5ClWZGtr9DFVOv3AV8MMtoLQpClgJVr43lscuj5FPfBEuXhHGBRPAyPV50+aIQW6/FEghG+Cx7Jgjx4ljTRVZ+fjTROlYyNNKmYwqLrRjcbHdQcqFqHvOQIBOl4RtJbSHhapi6XgslF+LeASGIISnS4KhqwUSrI5JKIelKHAA4xwoNuEb47vXFAx8NwIuDE+XGbXyG1YuX5itEmM2TcyROdiV14/AjVYRutplR1VLgJ/Yi95O2hr7N2rP3tSs0nnLfgVxEfOil3PEi99rGgbQLvF/UBG8u9g9+D3pgDKs+KlULx8jTWmmKBYwbX/pkLyfpL8X0ad/AQ== \ No newline at end of file diff --git a/img/RSPEC-flow-1.png b/img/RSPEC-flow-1.png deleted file mode 100644 index ec7e45587a..0000000000 Binary files a/img/RSPEC-flow-1.png and /dev/null differ