Merge branch 'master' into rule/add-RSPEC-S7129

.github/workflows/PullRequestClosed.yml

@@ -0,0 +1,29 @@
+name: Pull Request Closed
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  PullRequestMerged_job:
+    name: Pull Request Merged
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      pull-requests: read
+    # For external PR, ticket should be moved manually
+    if: |
+        github.event.pull_request.head.repo.full_name == github.repository
+        && github.event.pull_request.merged
+    steps:
+      - id: secrets
+        uses: SonarSource/vault-action-wrapper@v3
+        with:
+          secrets: |
+            development/kv/data/jira user | JIRA_USER;
+            development/kv/data/jira token | JIRA_TOKEN;
+      - uses: sonarsource/gh-action-lt-backlog/PullRequestClosed@v2
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          jira-user:  ${{ fromJSON(steps.secrets.outputs.vault).JIRA_USER }}
+          jira-token: ${{ fromJSON(steps.secrets.outputs.vault).JIRA_TOKEN }}

.github/workflows/RequestReview.yml

@@ -0,0 +1,28 @@
+name: Request review
+
+on:
+  pull_request:
+    types: ["review_requested"]
+
+jobs:
+  RequestReview_job:
+    name: Request review
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    # For external PR, ticket should be moved manually
+    if: |
+        github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - id: secrets
+        uses: SonarSource/vault-action-wrapper@v3
+        with:
+          secrets: |
+            development/github/token/{REPO_OWNER_NAME_DASH}-jira token | GITHUB_TOKEN;
+            development/kv/data/jira user | JIRA_USER;
+            development/kv/data/jira token | JIRA_TOKEN;
+      - uses: sonarsource/gh-action-lt-backlog/RequestReview@v2
+        with:
+          github-token: ${{ fromJSON(steps.secrets.outputs.vault).GITHUB_TOKEN }}
+          jira-user:    ${{ fromJSON(steps.secrets.outputs.vault).JIRA_USER }}
+          jira-token:   ${{ fromJSON(steps.secrets.outputs.vault).JIRA_TOKEN }}

.github/workflows/SubmitReview.yml

@@ -0,0 +1,30 @@
+name: Submit Review
+
+on:
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  SubmitReview_job:
+    name: Submit Review
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      pull-requests: read
+    # For external PR, ticket should be moved manually
+    if: |
+        github.event.pull_request.head.repo.full_name == github.repository
+        && (github.event.review.state == 'changes_requested'
+            || github.event.review.state == 'approved')
+    steps:
+      - id: secrets
+        uses: SonarSource/vault-action-wrapper@v3
+        with:
+          secrets: |
+            development/kv/data/jira user | JIRA_USER;
+            development/kv/data/jira token | JIRA_TOKEN;
+      - uses: sonarsource/gh-action-lt-backlog/SubmitReview@v2
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          jira-user: ${{ fromJSON(steps.secrets.outputs.vault).JIRA_USER }}
+          jira-token: ${{ fromJSON(steps.secrets.outputs.vault).JIRA_TOKEN }}

docs/description.adoc

@@ -271,6 +271,24 @@ 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.
 
+=== Comments within code blocks
+
+Colon (`:`) should be used as separator between `Noncompliant`/`Compliant` comments and the text explanation that follows, if any.
+
+[source,cpp]
+----
+int X = 2; // Noncompliant: variable should be in lowercase
+----
+
+
+When referencing a name within a comment in a code example, use double quotes to make it clear it refers to an existing element in the code.
+
+[source,cpp]
+----
+int i = 0;
+cout << noexcept(++i); // Noncompliant: "i" is not incremented
+----
+
 === 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

docs/metadata.adoc

@@ -40,6 +40,6 @@ You can update the quickfix field using this GitHub Workflow: https://github.com
 
 The code field is an object that contains information related to the clean code taxonomy. It is an object with two required properties:
 
-* `impacts`: A nested object that is treated as a mapping from a software quality to a level (`"LOW"`, `"MEDIUM"` or `"HIGH"`). Note that at least one software quality has to be specified. The current list of allowed software qualities is `"MAINTAINABILITY"`, `"RELIABILITY"` and `"SECURITY"`.
+* `impacts`: A nested object that is treated as a mapping from a software quality to a level (`"INFO"`, `"LOW"`, `"MEDIUM"`, `"HIGH"` or `"BLOCKER"`). Note that at least one software quality has to be specified. The current list of allowed software qualities is `"MAINTAINABILITY"`, `"RELIABILITY"` and `"SECURITY"`.
 
 * `attribute`: A single clean code attribute that the rule aims to achieve. This has to be one of the following values: `"FORMATTED"`, `"CONVENTIONAL"`, `"IDENTIFIABLE"`, `"CLEAR"`, `"LOGICAL"`, `"COMPLETE"`, `"EFFICIENT"`, `"FOCUSED"`, `"DISTINCT"`, `"MODULAR"`, `"TESTED"`, `"LAWFUL"`, `"TRUSTWORTHY"`, `"RESPECTFUL"`.

docs/styling_guide.adoc

@@ -109,3 +109,17 @@ Use it when referencing variable names, file names, tokens, and all kinds of spe
 Write:: Compiling source file `src/generic_file.py` breaks an `assert` call in pytest framework.
 Avoid:: Compiling source file "src/generic_file.py" breaks an `assert` call in `pytest` framework.
 
+== Referencing elements from the code
+
+When referencing elements from the code within a normal sentence, use the `backticks` (```) to format it. This includes variable names, function names, class names, and so on.
+
+When referencing the same elements within a comment in a code block, surrpond it with double quotes.
+[source,cpp]
+----
+int i = 0;
+// Write
+cout << noexcept(++i); // Noncompliant, "i" is not incremented -> Double quotes
+// Avoid
+cout << noexcept(++i); // Noncompliant, i is not incremented -> No quotes
+cout << noexcept(++i); // Noncompliant, `i` is not incremented -> Backticks
+----