Update education rule description documentation with more details (#1610)
This commit is contained in:
Christophe Zürn
GitHub
parent
2d6701452b
commit
62a99b38c5
@ -8,12 +8,13 @@ See also the <<styling_guide.adoc#,Styling Guidelines>>.
|
||||
|
||||
There should be no first level titles (`+= Title+`) in your adoc.
|
||||
|
||||
The following are the only allowed second level titles for H2:
|
||||
The following are the only allowed second level titles for H2 for standard and hotspot rules
|
||||
(for the education format, see the detailed <<3. Education Format,Education format>> section to see which headers are allowed):
|
||||
|
||||
include::./header_names/legacy_section_names.adoc[]
|
||||
|
||||
Most third-level titles (`+=== Title t3+`) are not checked, the only type of rule description for which some of these
|
||||
titles are checked are the progressive education rules (see below).
|
||||
Most third-level and fourth-level titles (`+=== Title t3+` and `+==== Title t4+`) are not checked, the only type of rule description for which some of these
|
||||
titles are checked are the education format rules (see below).
|
||||
|
||||
== Types of rule description
|
||||
|
||||
@ -57,17 +58,17 @@ The possible sections for this format are the following:
|
||||
. See
|
||||
. See Also
|
||||
|
||||
=== 3. Progressive Education
|
||||
=== 3. Education Format
|
||||
|
||||
Finally, the last format is the one related to the effort done on Progressive Education.
|
||||
This new format has a completely new structure, with additional subtitles and information,
|
||||
so as to be as comprehensible as possible for the users.
|
||||
Finally, the last format is the one related to the Progressive Education.
|
||||
This new format has a completely different structure, with additional subsections and information,
|
||||
to be as comprehensible as possible for the users.
|
||||
|
||||
This new structure is defined as follows:
|
||||
|
||||
... Short description (no title) ...
|
||||
* Short description (no title)
|
||||
|
||||
// This needs to be kept in sync with the [maps in the validation script](https://github.com/SonarSource/rspec/blob/3fb33d25c7bcfcde5a2426cb7177389cdcb6f5eb/rspec-tools/rspec_tools/validation/description.py#L32-L42).
|
||||
// This needs to be kept in sync with the [maps in the validation script](https://github.com/SonarSource/rspec/blob/master/rspec-tools/rspec_tools/validation/description.py#L33-L40).
|
||||
* Why is this an issue?
|
||||
** What is the potential impact?
|
||||
* How to fix it
|
||||
@ -79,7 +80,7 @@ This new structure is defined as follows:
|
||||
** Going the extra mile
|
||||
* How to fix it in {Framework Display Name}
|
||||
** Code examples
|
||||
*** Non-compliant examples
|
||||
*** Noncompliant code example
|
||||
*** Compliant solution
|
||||
** How does this work?
|
||||
** Pitfalls
|
||||
@ -90,14 +91,102 @@ This new structure is defined as follows:
|
||||
** Conference presentations
|
||||
** Standards
|
||||
|
||||
Where the `How to fix it in {Framework Display Name}` section can be repeated multiple times when the rule description is defined per-framework.
|
||||
|
||||
Content of the section "_3. How to fix it_" (i.e. subsections 3.a, 3.b, 3.c and 3.d) may be repeated multiple times, as
|
||||
each repetition will represent the specific _How to fix it_ section for a given framework.
|
||||
For example:
|
||||
The sections and subsections for this format are defined as follows:
|
||||
|
||||
* Short description (no title) [Optional]
|
||||
+
|
||||
A short introduction/summary of the topic, only a few sentences. +
|
||||
Goal: The title (or message) of a rule might not always be clear due to its shortness, and this should make it clear to our users what the issue is about. Experienced developers will immediately understand what it is about, and developers not yet familiar with the issue at hand can dig deeper into the `Why is this an issue?` section.
|
||||
+
|
||||
* *Why is this an issue?* (level 2 title) [Mandatory]
|
||||
+
|
||||
Start at the basics and go into more depth to explain the concepts behind this type of issue. This is most likely the place where a lot of the content will be. +
|
||||
Goal: Understand the concepts behind an issue.
|
||||
+
|
||||
* *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.
|
||||
https://github.com/SonarSource/rspec/blob/a51217c6d91abfa5e1d77d0ae0843e3903adf2d0/rules/S3649/impact.adoc[_Example._] +
|
||||
Goal: Our users should understand the impact of this issue on their project.
|
||||
+
|
||||
* *How to fix it* or *How to fix it in `{Framework Display Name}`* (level 2 title) [the title depends on whether the description is generic or framework-specifc. See examples below.]
|
||||
+
|
||||
This section consists of one or multiple fixes for this type of issue (`Noncompliant code example` vs. `Compliant solution`). There can be multiple fixes for different libraries and/or frameworks. +
|
||||
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]
|
||||
+
|
||||
Explain why this fixes the problem.
|
||||
+
|
||||
* *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]
|
||||
+
|
||||
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.
|
||||
https://github.com/SonarSource/rspec/blob/a51217c6d91abfa5e1d77d0ae0843e3903adf2d0/rules/S5131/common/extra-mile/csp.adoc[_Example._]
|
||||
+
|
||||
* *Resources* (level 2 title) [Optional]
|
||||
+
|
||||
Include resources if our users want to dig even deeper, that can be presented in the different categories.
|
||||
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]
|
||||
|
||||
Note that most sections and subsections are optional, only the `Why is this an issue?` and `How to fix it`/ `How to fix it in {Framework Display Name}` main
|
||||
sections are mandatory.
|
||||
|
||||
Content of the section "_How to fix it_ / _How to fix it in {Framework Display Name}_" can either be generic or framework specific.
|
||||
|
||||
When the content is generic, the "_How to fix it_" title must be used, and the section should only appear once. Example:
|
||||
....
|
||||
== Why is this an issue?
|
||||
Explanation of why this is bad.
|
||||
|
||||
== How to fix it
|
||||
|
||||
=== How to fix it in Spring
|
||||
=== Code examples
|
||||
|
||||
==== Noncompliant code example
|
||||
[source,js,diff-id=1,diff-type=noncompliant]
|
||||
----
|
||||
var myExample;
|
||||
----
|
||||
|
||||
==== Compliant solution
|
||||
[source,js,diff-id=1,diff-type=compliant]
|
||||
----
|
||||
var myExample = 0;
|
||||
----
|
||||
|
||||
=== How does this work?
|
||||
We added something.
|
||||
|
||||
== Resources
|
||||
=== Documentation
|
||||
http-address-of-documentation[My doc name]
|
||||
|
||||
....
|
||||
Note that you can see two special attributes (`diff-id` and `diff-type`) used in the code examples above, these attributes are explained in the <<Diff view,Diff view>>
|
||||
section below.
|
||||
|
||||
When the content is framework-specific, one or more "_How to fix it in `{Framework Display Name}`_" sections (with their respective subsections) must be present.
|
||||
Each repetition will represent the specific _How to fix it_ section of a given framework.
|
||||
For example:
|
||||
....
|
||||
== How to fix it in Spring
|
||||
|
||||
=== Code examples
|
||||
... Some generic text and code examples for Spring...
|
||||
|
||||
=== How does this work?
|
||||
@ -106,7 +195,9 @@ For example:
|
||||
=== Pitfalls
|
||||
... Generic and Spring-specific pitfalls to avoid when fixing the issue...
|
||||
|
||||
=== How to fix it in JSP
|
||||
== How to fix it in JSP
|
||||
|
||||
=== Code examples
|
||||
... Some generic text and code examples for JSP...
|
||||
|
||||
=== How does this work?
|
||||
@ -119,21 +210,25 @@ For example:
|
||||
Ideally, by convention and for maintainability, each framework _How to fix it_ section will be defined in separate files.
|
||||
Ex:
|
||||
....
|
||||
== How to fix it
|
||||
== Why is this an issue?
|
||||
... Explanation ...
|
||||
|
||||
# How to fix it sections
|
||||
|
||||
include::./how-to-fix-it/framework-1.adoc[]
|
||||
|
||||
include::./how-to-fix-it/framework-2.adoc[]
|
||||
|
||||
== Resources
|
||||
=== Documentation
|
||||
http-address-of-documentation[My doc name]
|
||||
....
|
||||
|
||||
Note that each framework-specific _How to fix it_ subsection must start with an H2 subtitle following the given format:
|
||||
`How to fix it in (?:(?:an|a|the)\\s)?(.*)`.
|
||||
Note that each framework-specific _How to fix it_ subsection must start with an H2 title following the given format:
|
||||
`== How to fix it in [an|a|the]? {Framework name}`.
|
||||
This is important, as this format will be expected by the analyzers when loading the rule content to recognize the different subsections.
|
||||
Furthermore, the display name of the framework has to match an allowed framework
|
||||
display name, as defined in <<allowed_framework_names.adoc#,this allowed framework names file>>.
|
||||
|
||||
Finally, additional information regarding each of the sections and subsections present in the educational rule description
|
||||
can be found https://docs.google.com/document/d/1caqBXTO1r7vftWrNXt_aNVe4rHcB5C6u6oKMBFjbzwo[in this document].
|
||||
display name, as defined in <<header_names/allowed_framework_names.adoc#,this allowed framework names file>>.
|
||||
|
||||
== Code Examples
|
||||
|
||||
@ -160,6 +255,30 @@ tsql:: use `sql`
|
||||
|
||||
In case no language is appropriate for a code block (for example shared examples between multiple languages), you can use `text` as the language.
|
||||
|
||||
=== Diff view
|
||||
|
||||
Additionally, you can also use two attributes to let the products know your code examples should be highlighted with a diff view when possible
|
||||
(showing the changes in the code examples as red/green).
|
||||
These attributes are optional and if a product does not yet support the diff view feature, these attributes will simply be ignored.
|
||||
|
||||
These attributes are `diff-id=X` and `diff-type=[noncompliant|compliant]`. The `diff-id` attributes describe which code examples should
|
||||
be compared together, and the `diff-type` attribute explain how it should be displayed `Noncompliant` (red) vs. `Compliant` (green).
|
||||
A single and unique diff-id should be used only once for each type of code example as shown in the description of a rule.
|
||||
....
|
||||
==== Noncompliant code example
|
||||
[source,js,diff-id=1,diff-type=noncompliant]
|
||||
----
|
||||
var myExample;
|
||||
----
|
||||
|
||||
==== Compliant solution
|
||||
[source,js,diff-id=1,diff-type=compliant]
|
||||
----
|
||||
var myExample = 0;
|
||||
----
|
||||
....
|
||||
|
||||
|
||||
== Parameters
|
||||
|
||||
Parameters should be listed in a subsection as follow:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user