Merge branch 'docs-new-branch-pipelines' into 'master'

Clarify rules for new branch pipelines

See merge request gitlab-org/gitlab!39230

doc/ci/yaml/README.md

@@ -304,6 +304,18 @@ To define your own `workflow: rules`, the configuration options currently availa
 
 If a pipeline attempts to run but matches no rule, it's dropped and doesn't run.
 
+Use the example rules below exactly as written to allow pipelines that match the rule
+to run. Add `when: never` to prevent pipelines that match the rule from running. See
+the [common `if` clauses for `rules`](#common-if-clauses-for-rules) for more examples.
+
+| Example rules                                        | Details                                                   |
+|------------------------------------------------------|-----------------------------------------------------------|
+| `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'` | Control when merge request pipelines run.                 |
+| `if: '$CI_PIPELINE_SOURCE == "push"'`                | Control when both branch pipelines and tag pipelines run. |
+| `if: $CI_COMMIT_TAG`                                 | Control when tag pipelines run.                           |
+| `if: $CI_COMMIT_BRANCH`                              | Control when branch pipelines run.                        |
+| `if: '$CI_COMMIT_BRANCH && $CI_COMMIT_BEFORE_SHA != "0000000000000000000000000000000000000000"'` | Control when pipelines run for new branches that are created or pushed with no commits. See the [skip job if branch is empty](#skip-job-if-branch-is-empty) example for more details. |
+
 For example, with the following configuration, pipelines run for all `push` events (changes to
 branches and new tags) as long as they *don't* have `-wip` in the commit message. Scheduled
 pipelines and merge request pipelines don't run, as there's no rule allowing them.
@@ -339,14 +351,6 @@ As with `rules` defined in jobs, be careful not to use a configuration that allo
 merge request pipelines and branch pipelines to run at the same time, or you could
 have [duplicate pipelines](#differences-between-rules-and-onlyexcept).
 
-Useful workflow rules clauses:
-
-| Clause                                                                     | Details                                                 |
-|----------------------------------------------------------------------------|---------------------------------------------------------|
-| `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'`                       | Allow or block merge request pipelines.                 |
-| `if: '$CI_PIPELINE_SOURCE == "push"'`                                      | Allow or block both branch pipelines and tag pipelines. |
-| `if: '$CI_COMMIT_BEFORE_SHA == '0000000000000000000000000000000000000000'` | Allow or block pipeline creation when new branches are created or pushed with no commits. This will also skip tag and scheduled pipelines. See [common `rules:if` clauses](#common-if-clauses-for-rules) for examples on how to define these rules more strictly. |
-
 #### `workflow:rules` templates
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0.
@@ -1365,27 +1369,17 @@ Other commonly used variables for `if` clauses:
 - `if: '$CUSTOM_VARIABLE == "value1"'`: If the custom variable `CUSTOM_VARIABLE` is
   exactly `value1`.
 
-To avoid running pipelines when a branch is created without any changes,
-check the value of `$CI_COMMIT_BEFORE_SHA`. It has a value of
-`0000000000000000000000000000000000000000`:
-
-- In branches with no commits.
-- In tag pipelines and scheduled pipelines. You should define rules very
-  narrowly if you don't want to skip these.
-
-To skip pipelines on all empty branches, but also tags and schedules:
+##### Skip job if branch is empty
 
-```yaml
-rules:
-  - if: $CI_COMMIT_BEFORE_SHA == '0000000000000000000000000000000000000000'
-    when: never
-```
+A branch has no commits if the value of`$CI_COMMIT_BEFORE_SHA` is
+`0000000000000000000000000000000000000000`. You can use this value to
+avoid running a job on branches with no commits.
 
-To skip branch pipelines when the branch is empty:
+To run a job only on branches with commits:
 
 ```yaml
 rules:
-  - if: $CI_COMMIT_BRANCH && $CI_COMMIT_BEFORE_SHA != '0000000000000000000000000000000000000000'
+  - if: '$CI_COMMIT_BRANCH && $CI_COMMIT_BEFORE_SHA != "0000000000000000000000000000000000000000"'
 ```
 
 #### `rules:changes`