docs(rules): add usage examples foreach rules (#135)

zenika-open-source · May 27, 2019 · 7b482d3 · 7b482d3
1 parent 268709c
commit 7b482d3
Show file tree

Hide file tree

Showing 5 changed files with 325 additions and 12 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -63,4 +63,7 @@ module.exports = {
     ],
   },
   gitwebhooksURL: 'https://webhooks-sklnx3jldq-uc.a.run.app',
+  markdown: {
+    toc: { includeLevel: [2, 2] },
+  },
 };
diff --git a/docs/rules/existingRules.md b/docs/rules/existingRules.md
@@ -2,7 +2,7 @@
 
 This section describes each existing rules: what's its goal and the `ruleResult` object returned by the `validate()` method that can be use for templating.
 
-<TOC :include-level="[2, 2]"/>
+[[toc]]
 
 ## BranchNameRule
 
@@ -22,6 +22,24 @@ Checks the branch's name according to a regular expression.
 }
 ```
 
+### Usage
+
+```yaml
+- name: branchName
+  options:
+    regexp: '^(fix|feature)/.*'
+  onError:
+    - callback: DeleteBranchRunnable #CAUTION!
+    - callback: LoggerRunnable
+      args:
+        message: 'Branch {{data.branch}} has been deleted because it does not begin with fix or feature.'
+  onSuccess:
+    - callback: CreatePullRequestRunnable
+      args:
+        title: 'WIP: {{data.branch}}'
+        description: 'Work in Progress Pull Request'
+```
+
 ## CheckAddedFilesRule
 
 ### Goal
@@ -39,6 +57,104 @@ Checks all added filenames in commits according to a regular expression.
 }
 ```
 
+### Usage
+
+```yaml
+- name: checkAddedFiles
+  options:
+    regexp: '*.exe$'
+  onSuccess:
+    - callback: DeleteFilesRunnable
+      args:
+        message: 'removing .exe file'
+```
+
+## CheckIssuesRule
+
+### Goal
+
+Return all Issues matching the filters options.
+
+::: tip
+Available in CRON jobs
+:::
+
+### `ruleResult` object
+
+```typescript
+{
+  validated: boolean,
+  data: {
+    issueNumber: number[]
+  }
+}
+```
+
+### Usage
+
+```yaml
+- name: checkIssues
+  options:
+    state: open
+    notUpdatedSinceXDays: 7
+  onSuccess:
+    - callback: LoggerRunnable
+      args:
+        type: warn
+        message: '{{data.issueNumber.length}} deserted Issue(s) founded. They will be closed. '
+    - callback: UpdateIssueRunnable
+      args:
+        state: close
+  onError:
+    - callback: LoggerRunnable
+      args:
+        type: info
+        message: 'No deserted Issue founded.'
+```
+
+## CheckPullRequestsRule
+
+### Goal
+
+Return all Pull Requests matching the filters options
+
+::: tip
+Available in CRON jobs
+:::
+
+### `ruleResult` object
+
+```typescript
+{
+  validated: boolean,
+  data: {
+    pullRequestNumber: number[]
+  }
+}
+```
+
+### Usage
+
+```yaml
+- name: checkIssues
+  options:
+    state: open
+    notUpdatedSinceXDays: 7
+  onSuccess:
+    - callback: LoggerRunnable
+      args:
+        type: warn
+        message: '{{data.issueNumber.length}} deserted Issue(s) founded. They will be closed. '
+    - callback: UpdateIssueRunnable
+      args:
+        state: close
+  onError:
+    - callback: LoggerRunnable
+      args:
+        type: info
+        message: 'No deserted Issue founded.'
+```
+
 ## CheckPullRequestStatusRule
 
 ### Goal
@@ -59,6 +175,20 @@ Checks if the Pull Request event matchs.
 }
 ```
 
+### Usage
+
+```yaml
+- name: checkPullRequestStatus
+  options:
+    status: reopened
+  onSuccess:
+    - callback: SendEmailRunnable
+      args:
+        to: bastien.terrier@gmail.com
+        subject: 'Pull Request #{{data.pullRequestNumber}} reopened '
+        message: '<b>{{data.pullRequestTitle}}</b> has been reopened, please pay attention!'
+```
+
 ## CheckVulnerabilitiesRule
 
 ### Goal
@@ -80,6 +210,28 @@ Available in CRON jobs
 }
 ```
 
+### Usage
+
+```yaml
+- name: checkVulnerabilities
+  onSuccess:
+    - callback: LoggerRunnable
+      args:
+        message: 'No vulnerability founded!'
+  onError:
+    - callback: LoggerRunnable
+      args:
+        message: '{{data.number}} vulnerabilities founded!'
+    - callback: WebhookRunnable
+      args:
+        url: 'https://webhook.site/0123-4567-89ab-cdef'
+        data: {
+          user: 'cron bot',
+          number: '{{data.number}}',
+          vulnerabilities: '{{{data.vulnerabilities}}}'
+        }
+```
+
 `vulnerabilities` contains all vulnerabilities returned by `npm audit` in JSON format.
 
 ## CommitMessageRule
@@ -104,6 +256,35 @@ Checks all commits title according to a regular expression and an optional max s
 }
 ```
 
+### Usage
+
+```yaml
+- name: commitMessage
+  options:
+    regexp: '^(feat|fix|docs)(\([a-z]+\))?:\s[^(]*(\(#[1-9][0-9]*(?:, #[1-9][0-9]*)*\))?$'
+    maxLength: 50
+  onSuccess:
+    - callback : WebhookRunnable
+      args:
+        url: 'https://webhook.site/0123-4567-89ab-cdef'
+        data: {
+          user: 'bot',
+          content: '{{#data.commits}}{{sha}} =
+          Object: {{matches.1}} | Scope: {{matches.2}} | Issue: {{matches.3}}
+          {{/data.commits}}'
+        }
+  onError:
+    - callback: LoggerRunnable
+      args:
+        message: 'Caution, commit(s): {{#data.commits}}{{sha}},{{/data.commits}} do not respect Good Practices!'
+  onBoth:
+    - callback: UpdateCommitStatusRunnable
+      args:
+        failTargetUrl: 'https://gist.github.com/stephenparish/9941e89d80e2bc58a153#examples'
+        successDescriptionMessage: 'Commit message matches the Good Practices!'
+        failDescriptionMessage: 'Caution, your commit message do not matches the Good Practices!'
+```
+
 ## IssueCommentRule
 
 ### Goal
@@ -124,6 +305,19 @@ Checks the new issue's comment according to a regular expression.
 }
 ```
 
+### Usage
+
+```yaml
+- name: issueComment
+  options:
+    regexp: '^ping @bastienterrier$'
+  onSuccess:
+    - callback: LoggerRunnable
+      args:
+        type: warn
+        message: 'Someone ping you!'
+```
+
 ## IssueTitleRule
 
 ### Goal
@@ -142,6 +336,20 @@ Checks the issue's title according to a regular expression.
 }
 ```
 
+### Usage
+
+```yaml
+- name: issueTitle
+  options:
+    regexp: '(fix|Fix)\s.*'
+  onSuccess:
+    - callback: SendEmailRunnable
+      args:
+        to: bastien.terrier@gmail.com
+        subject: 'New issue (#{{data.issueNumber}}) '
+        message: '<b>{{data.issueTitle}}</b> has been created!'
+```
+
 ## OneCommitPerPRRule
 
 ### Goal
@@ -163,6 +371,26 @@ Checks if there is only one commit in the current PR, MR or Push.
 }
 ```
 
+### Usage
+
+```yaml
+- name: oneCommitPerPR
+  onError:
+    - callback: LoggerRunnable
+      args:
+        message: 'more than one commit! A notification will be sent to the maintainer.'
+    - callback : WebhookRunnable
+      args:
+        url: 'https://webhook.site/0123-4567-89ab-cdef'
+        data: {
+          user: 'bot',
+          content: 'More than one commmit !',
+          commits: '{{#data.commits}}
+                      {{message}} (#{{id}})
+                    {{/data.commits}}',
+        }
+```
+
 ## PullRequestCommentRule
 
 ### Goal
@@ -184,6 +412,19 @@ Checks the new PR or MR's comment according to a regular expression.
 }
 ```
 
+### Usage
+
+```yaml
+- name: pullRequestComment
+  options:
+    regexp: '^ping @bastienterrier$'
+  onSuccess:
+    - callback: LoggerRunnable
+      args:
+        type: warn
+        message: 'Someone ping you!'
+```
+
 ## PullRequestTitleRule
 
 ### Goal
@@ -202,3 +443,15 @@ Checks the PR or MR's title according to a regular expression.
   }
 }
 ```
+
+### Usage
+
+```yaml
+- name: pullRequestTitle
+  options:
+    regexp: '^(WIP|FIX)\s:.*'
+  onError:
+    - callback: CommentPullRequestRunnable
+      args:
+        comment: 'ping @bastienterrier'
+```
diff --git a/src/rules/.rulesrc b/src/rules/.rulesrc
@@ -31,6 +31,23 @@ rules:
       - callback: CommentPullRequestRunnable
         args:
           comment: 'ping @bastienterrier'
+  - name: checkPullRequestStatus
+    options:
+      status: reopened
+    onSuccess:
+      - callback: SendEmailRunnable
+        args:
+          to: bastien.terrier@gmail.com
+          subject: 'Pull Request #{{data.pullRequestNumber}} reopened '
+          message: '<b>{{data.pullRequestTitle}}</b> has been reopened, please pay attention!'
+  - name: pullRequestComment
+    options:
+      regexp: '^ping @bastienterrier$'
+    onSuccess:
+      - callback: LoggerRunnable
+        args:
+          type: warn
+          message: 'Someone ping you!'
 
   # COMMITS
   - name: commitMessage
@@ -66,4 +83,20 @@ rules:
           message: 'removing .exe file'
 
   #ISSUES
-  - name: issueTitle
+  - name: issueTitle
+    options:
+      regexp: '(fix|Fix)\s.*'
+    onSuccess:
+      - callback: SendEmailRunnable
+        args:
+          to: bastien.terrier@gmail.com
+          subject: 'New issue (#{{data.issueNumber}}) '
+          message: '<b>{{data.issueTitle}}</b> has been created!'
+  - name: issueComment
+    options:
+      regexp: '^ping @bastienterrier$'
+    onSuccess:
+      - callback: LoggerRunnable
+        args:
+          type: warn
+          message: 'Someone ping you!'