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

Cross reference guides and cosmetics improvements (#2432)

Browse Source 
Indent sections in the rule description guide to improve readability.
Cross-reference the link standard in the rule description guide.

## Review

A dedicated reviewer checked the rule description successfully for:

- [x] logical errors and incorrect information
- [x] information gaps and missing content
- [x] text style and tone
- [x] PR summary and labels follow [the
guidelines](https://github.com/SonarSource/rspec/#to-modify-an-existing-rule)
This commit is contained in:
Marco Borgeaud 2023-07-11 09:18:38 +02:00 committed by GitHub
parent 5d433c2017
commit 3caf52608d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 13 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/description.adoc
View File

@ -80,7 +80,7 @@ what is going on. This can be in the form of noncompliant and compliant code in
detecting and why. Feel free to use “What is the potential impact?” title if it makes sense, or any other titles you find useful. +
Goal: Understand the concepts behind an issue.
+
* *What is the potential impact?* (level 3 title) [Optional]
** *What is the potential impact?* (level 3 title) [Optional]
+
What is the risk for me? What can go wrong?
This section can include multiple concrete threats as well.
@ -93,16 +93,16 @@ This section consists of one or multiple fixes for this type of issue (`Noncompl
If the fix for the rule is trivial (quickfix is available, it is easily inferred from the title and/or message), this section should be omitted and the fix could be mentioned in the previous section. +
Goal: Get an idea of how this issue can be fixed for my project/framework, why this works, what to look out for, and also how to continue improving on this topic.
+
* *How does this work?* (level 3 title) [Optional]
** *How does this work?* (level 3 title) [Optional]
+
Explain why this fixes the problem.
+
* *Pitfalls* (level 3 title) [Optional]
** *Pitfalls* (level 3 title) [Optional]
+
One or multiple pitfalls to take into account when working on fixing this issue.
https://github.com/SonarSource/rspec/blob/a51217c6d91abfa5e1d77d0ae0843e3903adf2d0/rules/S6096/common/pitfalls/partial-path-traversal.adoc[_Example._]
+
* *Going the extra mile* (level 3 title) [Optional]
** *Going the extra mile* (level 3 title) [Optional]
+
Even though the issue might be fixed, most of the time there can be way/s to further improve on this issue or to harden your project.
The subsection should be concise.
@ -114,15 +114,18 @@ Include resources if our users want to dig even deeper, that can be presented in
https://github.com/SonarSource/rspec/tree/a51217c6d91abfa5e1d77d0ae0843e3903adf2d0/rules/S5131/common/resources[_Example._] +
Goal: Allow the user to dig deeper by providing a curated list of resources.
+
* *Documentation* (level 3 title) [Optional]
* *Articles & blog posts* (level 3 title) [Optional]
* *Conference presentations* (level 3 title) [Optional]
* *Standards* (level 3 title) [Optional]
* *Benchmarks* (level 3 title) [Optional]
* *Related rules* (level 3 title) [Optional]
** *Documentation* (level 3 title) [Optional]
** *Articles & blog posts* (level 3 title) [Optional]
** *Conference presentations* (level 3 title) [Optional]
** *Standards* (level 3 title) [Optional]
** *Benchmarks* (level 3 title) [Optional]
** *Related rules* (level 3 title) [Optional]
+
This section lists Sonar rules related to the current one. The rule ID(s) should be followed by the rule title(s) or a sentence explaining the relation between the rules, e.g.: "_S2275 and S3457 specialize in detecting type mismatches with format strings._".
+
xref:link_formatting.adoc[Standard for links is defined in this document.]
Note that most sections and subsections are optional, only the `Why is this an issue?` main section is mandatory.