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

Fix the rule-id link format (#2408)

Browse Source 
Rule IDs are [automatically
transformed](https://github.com/SonarSource/sonar-rule-api/blob/master/src/main/java/com/sonarsource/ruleapi/asciidoctor/AsciiDoctorConverter.java#L111)
into link placeholders by rule-api. These placeholders are translated
into autolinks by the products.
If these IDs appear within other links, it might [break some
products](https://discuss.sonarsource.com/t/cross-rule-references-inside-a-tags-in-html-rule-descriptions/14971/4).

Moreover, the generated autolinks are product-specific, and cannot be
encoded statically in the rule description.
This commit is contained in:
Arseniy Zaostrovnykh 2023-07-05 16:30:33 +02:00 committed by GitHub
parent 41dd7a1cc3
commit 543d93befd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 5 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/link_formatting.adoc
View File

@ -10,7 +10,9 @@ We often want to provide links in the 'Resources' section of a rule that point t
* Links to framework documentation <source> - <member name and kind> e.g. Microsoft Learn - Object.ToString Method * Links to framework documentation <source> - <member name and kind> e.g. Microsoft Learn - Object.ToString Method
* Links to blog posts / news articles: <source> - <title> e.g. Google Security Blog - Moving towards a more secure web * Links to blog posts / news articles: <source> - <title> e.g. Google Security Blog - Moving towards a more secure web
* Links to Stack Overflow answers (similar comments in a blog)e.g. Stack Overflow - Answer by Stephen Cleary for Best way to handle null task inside async method? * Links to Stack Overflow answers (similar comments in a blog)e.g. Stack Overflow - Answer by Stephen Cleary for Best way to handle null task inside async method?
* Link to another Sonar rule: <rulenumber> - <title> e.g. S2755 - XML parsers should not be vulnerable to XXE attacks (note, linking to rules.sonarsource.com) * Links to another Sonar rule: <rulenumber> - <title> e.g. S2755 - XML parsers should not be vulnerable to XXE attacks.
Note that rule-ids (`<rulenumber>`) are automatically hyperlinked in our products to point to the rule description in that product.
_Do not add any hyperlink yourself._
The hyperlink to anything apart from other Sonar rules should be applied to just the document name, with the 'source' being left as plain text. The idea is that this makes it really easy for a user to understand the source before they click on anything. The hyperlink to anything apart from other Sonar rules should be applied to just the document name, with the 'source' being left as plain text. The idea is that this makes it really easy for a user to understand the source before they click on anything.
For Sonar rules, the whole entry (<rulenumber> - <title>) should be a hyperlink. For Sonar rules, the whole entry (<rulenumber> - <title>) should be a hyperlink.
@ -21,7 +23,8 @@ Here is how the above links should look like:
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/system.object.tostring[`Object.ToString` Method] * Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/system.object.tostring[`Object.ToString` Method]
* Google Security Blog - https://security.googleblog.com/2016/09/moving-towards-more-secure-web.html[Moving towards a more secure web] * Google Security Blog - https://security.googleblog.com/2016/09/moving-towards-more-secure-web.html[Moving towards a more secure web]
* Stack Overflow - Answer by Stephen Cleary for https://stackoverflow.com/a/27551261[Best way to handle null task inside async method?] * Stack Overflow - Answer by Stephen Cleary for https://stackoverflow.com/a/27551261[Best way to handle null task inside async method?]
* https://rules.sonarsource.com/java/RSPEC-2755[S2755 - XML parsers should not be vulnerable to XXE attacks] * S2755 - XML parsers should not be vulnerable to XXE attacks +
_Note, no link here, this is the intended behavior. In the products the "S2755" part will be automatically hyperlinked._
=== Additional things to consider when adding a link to a rule: === Additional things to consider when adding a link to a rule: