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

Address the feedback from user studies in wording of the readme.

Browse Source
This commit is contained in:
Arseniy Zaostrovnykh 2021-04-28 12:01:25 +02:00 committed by GitHub
parent dfc955af1e
commit 0d4a864a58
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 25 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
README.adoc
View File

@ -17,7 +17,7 @@ WARNING: **Beta status**: This repository is not used yet in production. The cur
** `rules/Sxxxx`: contains every specification for rule `Sxxxx`.
*** `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. `[LANGUAGE]` can be `java`, `cfamily`, `python`...
*** `rules/Sxxxx/[LANGUAGE]`: contains the language-specific RSPEC. For every rule, there must be at least one `[LANGUAGE]` subdirectory. `[LANGUAGE]` can be `java`, `cfamily`, `python`...
**** `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.
@ -36,21 +36,35 @@ However, one of the reasons we are migrating to a git repository is that we want
=== 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.
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.
4. click on the green _Run workflow_ button.
image::img/new-rule-workflow.png[]
==== To modify an existing rule
Create a pull request manually
Create a branch for your modifications manually.
Then open a pull request manually.
In the subject add the following text:
----
MODIFIES RULE: Sxxxx
----
NOTE: use a GitHub hot-key `t` in the source view to navigate to an existing rule specification.
=== 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.
You should see https://github.com/pulls/assigned[a new pull request assigned to you]. It might take up to a minute to appear.
It contains a scaffolding of files for the new rule. Feel free to modify it as you please.
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
@ -75,7 +89,8 @@ 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.
Implement the rule, update analyzer's metadata, and merge the rule implementation in your analyzer repository.
Afterwards, merge the RSPEC pull request.
==== Generate/Update rule metadata for the analyzer

1
img/RSPEC-flow-1.drawio Normal file
View File

@ -0,0 +1 @@
<mxfile modified="2021-04-27T15:17:15.934Z" host="app.diagrams.net" agent="5.0 (X11)" etag="NAIBM7ySNy3tkXIqtkWB" version="14.4.3" type="device"><diagram id="C2fSY1v2SiZeoUbDoYyL" name="Page-1">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==</diagram></mxfile>

BIN
img/RSPEC-flow-1.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 23 KiB

1
img/RSPEC-flow-2.drawio Normal file
View File

@ -0,0 +1 @@
<mxfile modified="2021-04-27T15:16:21.010Z" host="app.diagrams.net" agent="5.0 (X11)" etag="OVOza-A59J8keATMf0ue" version="14.4.3" type="device"><diagram id="C2fSY1v2SiZeoUbDoYyL" name="Page-1">3VlbV6MwEP41fbQHAgX7qLXq8eged7tnvbxFiBA3EDYEW/z1m5S0XFtbWyl6eCCZTALzfZOZIfSMUTC7YDDyb6iLSA9o7qxnnPUA0IeWKW5SkmYSe2BkAo9hVynlggl+Q0qoKWmCXRSXFDmlhOOoLHRoGCKHl2SQMTotqz1TUn5qBD1UE0wcSOrSO+xyX0l1a5gPXCLs+erRx8DOBgK4UFaWxD506bQgMsY9Y8Qo5VkrmI0QkeAtcMnmna8YXb4YQyHfZAKYBr8f727vzOnQ+mOFP/7dvFwdqVVeIUmUwVeYQSH5Nbkdj9SL83SBBqNJ6CK5oN4zTqc+5mgSQUeOTgX/QubzgKjhZxryESWUzeca1lheQh5zRv+ippG6SYv3Q4yjWUGkTLxANECcpUJF+RdQvEwLZJmKAb/Ak6VkUPmHt1wph1A0FIrbIGrVUEOucCnVpYz71KMhJONceprjqolernNNaaTQfEGcp2p/wITTMtZohvl9of0gl+oPVO9splaed1LVWYl2TBPmoDU2ArURIfMQX6Ontrq0fy13DBHI8Wt5y+2fGfurMCMIYel9sVOYJbv5tHmvPUbNTjEKjEMymrP4UCTxHUZzEh9KHDYz6sLYX8bbz6dX3ze986knjMG0oBBRHPK4sPKtFAgFFeENQwVnFdOH5bxW0bbXKItG9vDcx5ZW7OB2g+64nf4ht9Pfcbtq6p5fTalbm1+t+Oagk765pXe245+1oq4HLMJlOMGvounJ5onwvfQNsXgxJh5VGN6t9NulkFOjVeSOGwo70GZhZ9RQnfwUC03kapPrg+NlWhVPa8Br0CZe5iZeyBKC4n4sAiHLAkXfoUFHPbKKsG4eGmL9oPVPGxVtm4losGEiAt2qgYeHLUbsj1Qj2znBarJXHTG04AR2J8oRsxL0tfXVSFXdaqEaGdTywAXml8lTfsgkMIrobuH9A/Fg8zOlxkDf6qESqJ/Tycx5BCNcw00YxdeBE9JQhoBnTEhFBAn2QtF1BFRIyE8lRNiB5EQNBNh15/GjiY1yTNlDvl3m0gUNWp2GpnQLPo2FemEtdjeCMfq+JJiGXiHBPjAJ9boyiVzIBQeaQ4VhwnqgERh6CfRQ3FFmtk5cW2ybxgORUuyyWiXM2jdh3d81VQ5AQ+hqlwVdrwH7zT4V9nRUuvjJ+MW+AuzaJit+VHuY+8lTH4sq65zFEXJ2q7b2sENA9RzNqO8QoO2nxpJGL3+zZmVt/rPaGP8H</diagram></mxfile>

BIN
img/RSPEC-flow-2.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 23 KiB

1
img/RSPEC-flow.drawio
View File

@ -1 +0,0 @@
<mxfile modified="2021-02-19T15:04:41.376Z" host="app.diagrams.net" agent="5.0 (X11)" etag="Y9FQjmlkbswknfFz2YXr" version="14.4.2" type="device"><diagram id="C2fSY1v2SiZeoUbDoYyL" name="Page-1">3VrZcpswFP0aPybDTvzoOk4ymaST1p2m6ZsCCiiVERUitvP1lUCYRbaD4wXXw4PR1YbOOffqItwzh5PZNQVxeE98iHuG5s965mXPMPS+Y/EfYZnnFtc2c0NAkS8blYYxeofSqElrinyY1BoyQjBDcd3okSiCHqvZAKVkWm/2QnB91hgEUDGMPYBV6yPyWSitutMvK24gCkI59YXh5hUTUDSWK0lC4JNpxWSOeuaQEsLyu8lsCLEAr8Al73e1onbxYBRGrE0HYzr58fvx4dGa9p2fTvT17/3r7ZluyIdj82LF0OcAyCKhLCQBiQAeldYvlKSRD8WwGi+Vbe4IiblR58ZXyNhcsglSRrgpZBMsa+EMsV+i+7ktS0+VmsuZHDkrzItCxOi80kkUn6p1ZbesVPTL1ycWtRI3aUpISj24DiypP0ADyNa0sxfscreAZAL58/B+FGLA0Fv9OYDUZ7BoV1LIbySLmzCaj/sGcCpnukUUcMv38cNoqLBdcingn4aIwXEMMhim3KPrvMmhIWVwth5NdfXS/y3pDdOKMxW2sOJHjrYvfJwuFa9X9F6qf7nid6hco6VyzU6V6/4vzJSxqBaJysC0/1jUllGrS0YN83h2F60lo53tLm0ZXRFfWzOadR1QCuaVBjFBEUsqIz8IA28g47xpyngsw3gz12g0d9e15jf59KWwFuvYQmv28Wjtc5mM/oHWXkjEhgQTmq3OdLKL2xNGyR9YqdGyi9f4IAkXe3sHUt02EdqNVK3NtGodQqxKktYzHMwEZeiN3wbidsCFOH+HNCnq+FSV6u5SOdmhiZyuLcntjEPmdqYC6/gbH2gsRhvfdQ6Y5dQBW5YL24fEy2ojQ5pimJwnPCzSPDCce2RypJJsIqw7XUOsd5oCHSKpPZ5tyW65LRmd5sT9bvMU9zOJymaKqPG7WgZN4YzE1ZEi3C4lYSth+Bqxm/S5PLThDxKT7aLr5m66TTxeF38Pe9yj7nFwFnMPElB6FMVMgZUvl9Wxq2MUkUj45AvCuGECGAURL3ocHsjtXwR4yAN4ICsmyPczh15GVt3Jd5GgNTZDQyVjGRfGvrgoVlDhQiQXZyBGp0vCIt1Yw8KyjGR/LKgvHzzMQZDA0yXBMvU6CfpFxySoYSmNfcA4B5pH+Fr56g0NgyhIQQCT02VGd5fsEM5BqXB2TcWeUV+1k++SjeIwRO+aHV1XAD+x96fe7tLdth8ou30BchV/qx4uBIiF6fM54unuFU1i6InZxIeEK0UIG+W/Sp57MRDXh+8h22VgzbNIW/UnQ9tNPizwWvyZID+oLP+SYY7+AQ==</diagram></mxfile>

BIN
img/new-rule-workflow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 318 KiB