Merge branch 'patch-178' into 'master'

Add headers in syntax of env variable expressions section

See merge request gitlab-org/gitlab!36006

doc/ci/variables/README.md

@@ -649,94 +649,98 @@ This follows the usual rules for [`only` / `except` policies](../yaml/README.md#
 
 ### Syntax of environment variable expressions
 
-Below you can find supported syntax reference:
+Below you can find supported syntax reference.
 
-1. Equality matching using a string
+#### Equality matching using a string
 
-   Examples:
+Examples:
 
-   - `$VARIABLE == "some value"`
-   - `$VARIABLE != "some value"` (introduced in GitLab 11.11)
+- `$VARIABLE == "some value"`
+- `$VARIABLE != "some value"` (introduced in GitLab 11.11)
 
-   You can use equality operator `==` or `!=` to compare a variable content to a
-   string. We support both, double quotes and single quotes to define a string
-   value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'`
-   are supported. `"some value" == $VARIABLE` is correct too.
+You can use equality operator `==` or `!=` to compare a variable content to a
+string. We support both, double quotes and single quotes to define a string
+value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'`
+are supported. `"some value" == $VARIABLE` is correct too.
 
-1. Checking for an undefined value
+#### Checking for an undefined value
 
-   Examples:
+Examples:
 
-   - `$VARIABLE == null`
-   - `$VARIABLE != null` (introduced in GitLab 11.11)
+- `$VARIABLE == null`
+- `$VARIABLE != null` (introduced in GitLab 11.11)
 
-   It sometimes happens that you want to check whether a variable is defined
-   or not. To do that, you can compare a variable to `null` keyword, like
-   `$VARIABLE == null`. This expression evaluates to true if
-   variable is not defined when `==` is used, or to false if `!=` is used.
+It sometimes happens that you want to check whether a variable is defined
+or not. To do that, you can compare a variable to `null` keyword, like
+`$VARIABLE == null`. This expression evaluates to true if
+variable is not defined when `==` is used, or to false if `!=` is used.
 
-1. Checking for an empty variable
+#### Checking for an empty variable
 
-   Examples:
+Examples:
 
-   - `$VARIABLE == ""`
-   - `$VARIABLE != ""` (introduced in GitLab 11.11)
+- `$VARIABLE == ""`
+- `$VARIABLE != ""` (introduced in GitLab 11.11)
 
-   If you want to check whether a variable is defined, but is empty, you can
-   simply compare it against an empty string, like `$VAR == ''` or non-empty
-   string `$VARIABLE != ""`.
+If you want to check whether a variable is defined, but is empty, you can
+simply compare it against an empty string, like `$VAR == ''` or non-empty
+string `$VARIABLE != ""`.
 
-1. Comparing two variables
+#### Comparing two variables
 
-   Examples:
+Examples:
 
-   - `$VARIABLE_1 == $VARIABLE_2`
-   - `$VARIABLE_1 != $VARIABLE_2` (introduced in GitLab 11.11)
+- `$VARIABLE_1 == $VARIABLE_2`
+- `$VARIABLE_1 != $VARIABLE_2` (introduced in GitLab 11.11)
 
-   It is possible to compare two variables. This is going to compare values
-   of these variables.
+It is possible to compare two variables. This is going to compare values
+of these variables.
 
-1. Variable presence check
+#### Variable presence check
 
-   Example: `$STAGING`
+Example: `$STAGING`
 
-   If you only want to create a job when there is some variable present,
-   which means that it is defined and non-empty, you can simply use
-   variable name as an expression, like `$STAGING`. If `$STAGING` variable
-   is defined, and is non empty, expression will evaluate to truth.
-   `$STAGING` value needs to be a string, with length higher than zero.
-   Variable that contains only whitespace characters is not an empty variable.
+If you only want to create a job when there is some variable present,
+which means that it is defined and non-empty, you can simply use
+variable name as an expression, like `$STAGING`. If `$STAGING` variable
+is defined, and is non empty, expression will evaluate to truth.
+`$STAGING` value needs to be a string, with length higher than zero.
+Variable that contains only whitespace characters is not an empty variable.
 
-1. Pattern matching (introduced in GitLab 11.0)
+#### Regex pattern matching
 
-   Examples:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43601) in GitLab 11.0
 
-   - `=~`: True if pattern is matched. Ex: `$VARIABLE =~ /^content.*/`
-   - `!~`: True if pattern is not matched. Ex: `$VARIABLE_1 !~ /^content.*/` ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/61900) in GitLab 11.11)
+Examples:
 
-   Variable pattern matching with regular expressions uses the
-   [RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax).
-   Expressions evaluate as `true` if:
+- `=~`: True if pattern is matched. Ex: `$VARIABLE =~ /^content.*/`
+- `!~`: True if pattern is not matched. Ex: `$VARIABLE_1 !~ /^content.*/` ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/61900) in GitLab 11.11)
 
-   - Matches are found when using `=~`.
-   - Matches are *not* found when using `!~`.
+Variable pattern matching with regular expressions uses the
+[RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax).
+Expressions evaluate as `true` if:
 
-   Pattern matching is case-sensitive by default. Use `i` flag modifier, like
-   `/pattern/i` to make a pattern case-insensitive.
+- Matches are found when using `=~`.
+- Matches are *not* found when using `!~`.
 
-1. Conjunction / Disjunction ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27925) in GitLab 12.0)
+Pattern matching is case-sensitive by default. Use `i` flag modifier, like
+`/pattern/i` to make a pattern case-insensitive.
 
-   Examples:
+#### Conjunction / Disjunction
 
-   - `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"`
-   - `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3`
-   - `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3`
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62867) in GitLab 12.0
 
-   It is possible to join multiple conditions using `&&` or `||`. Any of the otherwise
-   supported syntax may be used in a conjunctive or disjunctive statement.
-   Precedence of operators follows the
-   [Ruby 2.5 standard](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html),
-   so `&&` is evaluated before `||`.
+Examples:
+
+- `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"`
+- `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3`
+- `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3`
+
+It is possible to join multiple conditions using `&&` or `||`. Any of the otherwise
+supported syntax may be used in a conjunctive or disjunctive statement.
+Precedence of operators follows the
+[Ruby 2.5 standard](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html),
+so `&&` is evaluated before `||`.
 
 ### Storing regular expressions in variables