docs: add clarification to ruleset matcher (go-vela#223)

* docs: reorder ruleset reference * docs: add clarification to ruleset matcher * docs: update wording in ruleset example Co-authored-by: David May <1301201+wass3r@users.noreply.github.com> * docs: make regexp ruleset comments consistent * docs: make comments consistent Co-authored-by: David May <1301201+wass3r@users.noreply.github.com>
bancambios · May 27, 2021 · 664c987 · 664c987
1 parent 5a8e7bb
commit 664c987
Showing 1 changed file with 37 additions and 33 deletions.
diff --git a/content/reference/yaml/steps.md b/content/reference/yaml/steps.md
@@ -133,7 +133,7 @@ The following rules can be used to configure a ruleset:
 ---
 steps:
   - ruleset:
-      # Below is displaying a step that would execute if the build
+      # As shown below this step will execute if the build
       # branch is stage or master.
       branch: [ stage, master ]
 ```
@@ -143,7 +143,7 @@ steps:
 steps:
   - ruleset:
       # This extends the ability to start new builds through interactions
-      # within a pull request. Below is displaying it will run a step if a “run build”
+      # within a pull request. As shown below this will run a step if a “run build”
       # comment is added to the bottom of a pull request.
       comment: [ "run build" ]
 ```
@@ -152,7 +152,7 @@ steps:
 ---
 steps:
   - ruleset:
-      # Below is displaying a step that would execute if the build
+      # As shown below this step will execute if the build
       # event is push or pull_request. The available events are:
       # comment, push, pull_request, tag, and deployment.
       event: [ push, pull_request ]
@@ -162,7 +162,7 @@ steps:
 ---
 steps:
   - ruleset:
-      # Below is displaying it will run a step if file README.md, any file of type *.md
+      # As shown below this step will execute if file README.md, any file of type *.md
       # in the root directory or any file in the test/* directory has changed.
       path: [ README.md, "*.md", "test/*" ]
 ```
@@ -171,7 +171,7 @@ steps:
 ---
 steps:
   - ruleset:
-      # Below is displaying it will run a step if repo exists within the target GitHub
+      # As shown below this step will execute if repo exists within the target GitHub
       # organization or the repo is the go-vela/docs repository.
       repo: [ "target/*", "go-vela/docs" ]
 ```
@@ -180,82 +180,85 @@ steps:
 ---
 steps:
   - ruleset:
-      # Below is displaying it will run a step if the build status is failure or success.
+      # As shown below this step will execute if the build status is failure or success.
       status: [ failure, success ]
 ```
 
 ```yaml
 ---
 steps:
   - ruleset:
-      # Below is displaying it will run a step if the build ref is dev/* or test/*.
+      # As shown below this step will execute if the build ref is dev/* or test/*.
       tag: [ dev/*, test/* ]
 ```
 
 ```yaml
 ---
 steps:
   - ruleset:
-      # Below is displaying it will run a step if the build target is stage or production.
+      # As shown below this step will execute if the build target is stage or production.
       # This tag is only compatible with deployment events.
       target: [ dev/*, test/* ]
 ```
 
 The following controls can be used to modify the behavior of the ruleset evaluation:
 
-| Name       | Description                                        |
-|------------|----------------------------------------------------|
-| `continue` | enables continuing the build if the step fails.    |
-| `if`       | limits the step execution to all rules must match. |
-| `matcher`  | matcher to use when evaluating the ruleset.        |
-| `operator` | operator to use when evaluating the ruleset.       |
-| `unless`   | limits the step execution to no rules can match.   |
+| Name       | Description                                        | Options                                                                 |
+|------------|----------------------------------------------------| ----------------------------------------------------------------------- |
+| `continue` | enables continuing the build if the step fails.    | `true`, `false`                                                         |
+| `matcher`  | matcher to use when evaluating the ruleset.        | `filepath`, `regexp`                                                    |
+| `operator` | operator to use when evaluating the ruleset.       | `and`, `or`                                                             |
+| `if`       | limits the step execution to all rules must match. | `branch`, `comment`, `event`, `path`, `repo`, `status`, `tag`, `target` |
+| `unless`   | limits the step execution to no rules can match.   | `branch`, `comment`, `event`, `path`, `repo`, `status`, `tag`, `target` |
 
 ```yaml
 ---
 steps:
   - ruleset:
-      # Below is displaying it will allow the step to continue the sequential step
-      # pipeline when this step fails.
+      # As shown below this will overwrite Vela's default behavior to
+      # allow the build to continue the sequential step pipeline when this step fails.
       continue: true
 ```
 
 ```yaml
 ---
 steps:
   - ruleset:
-      # Below is displaying it will is an explicit way to tell the ruleset
-      # to only execute this step when the branch is master and event is push.
-      if:
-        branch: master
-        event: push
+      # As shown below this will overwrite Vela's default behavior to use a 
+      # filepath matcher and instead evaluate all rules with regex. The available
+      # matchers are: filepath, and regexp.
+      # Note: The regexp matcher uses Go's regexp package. You can find documentation
+      # at https://golang.org/pkg/regexp/syntax/
+      matcher: regexp
+      branch: foo-\\d
 ```
 
 ```yaml
 ---
 steps:
   - ruleset:
-      # Below is displaying it will overwrite Vela's default behavior to use a 
-      # filepath matcher and instead evaluate all rules with regex. The available
-      # matchers are: filepath, and regexp.
-      matcher: regexp
+      # As shown below this will overwrite Vela's default behavior to use an 
+      # "or" behavior when comparing all ruleset rules.
+      # The available operators are: and, and or.
+      operator: or
 ```
 
 ```yaml
 ---
 steps:
   - ruleset:
-      # Below is displaying it will overwrite Vela's default behavior to use a 
-      # "and" behavior when comparing all ruleset rules. The available
-      # operators are: and, and or.
-      operator: or
+      # As shown below this will tell the ruleset to only execute
+      # this step when the branch is master and event is push.
+      if:
+        branch: master
+        event: push
 ```
 
 ```yaml
 ---
 steps:
   - ruleset:
-      # Below is displaying it will is an explicit way to tell the ruleset
+      # As shown below this will overwrite Vela's default behavior to tell the ruleset
       # to only execute this step when the branch is not master and event is not push.
       unless:
         branch: master
@@ -268,8 +271,9 @@ steps:
 ---
 steps:
     # Extra configuration variables specific to a plugin. All tags within the 
-    # parameters tag are injected environment variables into the container
-    # as PARAMETER_<TAG_NAME>. Below is illustrating a plugin that needs to fields:
+    # parameters tag are injected environment variables into the
+    # container as PARAMETER_<TAG_NAME>.
+    # As shown below this step will execute a plugin that needs two fields:
     # PARAMETERS_REGISTRY=index.docker.io
     # PARAMETERS_REPO=octocat/hello-world,go-vela/docs
   - parameters: