Merge branch 'docs-parentheses-availability' into 'master'

Update parenthesis variable docs

Closes #232805

See merge request gitlab-org/gitlab!40575

doc/ci/variables/README.md

@@ -744,7 +744,11 @@ so `&&` is evaluated before `||`.
 
 #### Parentheses
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3
+> - It's [deployed behind a feature flag](../../user/feature_flags.md), enabled by default.
+> - It's enabled on GitLab.com.
+> - It's recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-parenthesis-support-for-variables-core-only). **(CORE ONLY)**
 
 It is possible to use parentheses to group conditions. Parentheses have the highest
 precedence of all operators. Expressions enclosed in parentheses are evaluated first,
@@ -760,20 +764,22 @@ Examples:
 - `($VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/) && $VARIABLE3`
 - `$CI_COMMIT_BRANCH == "my-branch" || (($VARIABLE1 == "thing" || $VARIABLE2 == "thing") && $VARIABLE3)`
 
+##### Enable or disable parenthesis support for variables **(CORE ONLY)**
+
 The feature is currently deployed behind a feature flag that is **enabled by default**.
 [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
 can opt to disable it for your instance.
 
-To enable it:
+To disable it:
 
 ```ruby
-Feature.enable(:ci_if_parenthesis_enabled)
+Feature.disable(:ci_if_parenthesis_enabled)
 ```
 
-To disable it:
+To enable it:
 
 ```ruby
-Feature.disable(:ci_if_parenthesis_enabled)
+Feature.enable(:ci_if_parenthesis_enabled)
 ```
 
 ### Storing regular expressions in variables

doc/ci/yaml/README.md

@@ -1548,6 +1548,22 @@ considered for their usage and behavior in this context. Future keyword improvem
 are being discussed in our [epic for improving `rules`](https://gitlab.com/groups/gitlab-org/-/epics/2783),
 where anyone can add suggestions or requests.
 
+You can use [parentheses](../variables/README.md#parentheses) with `&&` and `||` to build more complicated variable expressions.
+[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3:
+
+```yaml
+job1:
+  script:
+    - echo This rule uses parentheses.
+  rules:
+    if: ($CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE
+```
+
+NOTE: **Note:**
+In GitLab 13.2 and older, the order of operations when mixing `||` and `&&` in a single rule may not have executed
+in the expected order. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/230938)
+in GitLab 13.3.
+
 ### `only`/`except` (basic)
 
 NOTE: **Note:**
@@ -1833,7 +1849,17 @@ end-to-end:
       - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
 ```
 
-Learn more about [variables expressions](../variables/README.md#environment-variables-expressions).
+You can use [parentheses](../variables/README.md#parentheses) with `&&` and `||` to build more complicated variable expressions.
+[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3:
+
+```yaml
+job1:
+  script:
+    - echo This rule uses parentheses.
+  only:
+    variables:
+      - ($CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE
+```
 
 #### `only:changes`/`except:changes`