Merge branch 'docs-vale-master-rule' into 'master'

Add a vale rule to check for usage of "master"

See merge request gitlab-org/gitlab!55148

doc/.vale/gitlab/DefaultBranch.yml

+---
+# Warning: gitlab.DefaultBranch
+#
+# Do not refer to the default branch as the "master" branch, if possible.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: existence
+message: 'Use "default branch" or `main` instead of `master`, when possible.'
+level: warning
+ignorecase: true
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html
+scope: raw
+raw:
+  - '\`master\`'

doc/ci/environments/deployment_safety.md

@@ -74,15 +74,15 @@ runs by enabling the [Skip outdated deployment jobs](../pipelines/settings.md#sk
 
 Example of a problematic pipeline flow **before** enabling Skip outdated deployment jobs:
 
-1. Pipeline-A is created on the `master` branch.
-1. Later, Pipeline-B is created on the `master` branch (with a newer commit SHA).
+1. Pipeline-A is created on the default branch.
+1. Later, Pipeline-B is created on the default branch (with a newer commit SHA).
 1. The `deploy` job in Pipeline-B finishes first, and deploys the newer code.
 1. The `deploy` job in Pipeline-A finished later, and deploys the older code, **overwriting** the newer (latest) deployment.
 
 The improved pipeline flow **after** enabling Skip outdated deployment jobs:
 
-1. Pipeline-A is created on the `master` branch.
-1. Later, Pipeline-B is created on the `master` branch (with a newer SHA).
+1. Pipeline-A is created on the default branch.
+1. Later, Pipeline-B is created on the default branch (with a newer SHA).
 1. The `deploy` job in Pipeline-B finishes first, and deploys the newer code.
 1. The `deploy` job in Pipeline-A is automatically cancelled, so that it doesn't overwrite the deployment from the newer pipeline.
 

doc/ci/examples/authenticating-with-hashicorp-vault/index.md

@@ -180,7 +180,7 @@ $ vault write auth/jwt/config \
 
 For the full list of available configuration options, see Vault's [API documentation](https://www.vaultproject.io/api/auth/jwt#configure).
 
-The following job, when run for the `master` branch, is able to read secrets under `secret/myproject/staging/`, but not the secrets under `secret/myproject/production/`:
+The following job, when run for the default branch, is able to read secrets under `secret/myproject/staging/`, but not the secrets under `secret/myproject/production/`:
 
 ```yaml
 read_secrets:

doc/ci/examples/deployment/composer-npm-deploy.md

@@ -122,7 +122,7 @@ Therefore, for a production environment we use additional steps to ensure that a
 
 Since this was a WordPress project, I gave real life code snippets. Some further ideas you can pursue:
 
-- Having a slightly different script for `master` branch allows you to deploy to a production server from that branch and to a stage server from any other branches.
+- Having a slightly different script for the default branch allows you to deploy to a production server from that branch and to a stage server from any other branches.
 - Instead of pushing it live, you can push it to WordPress official repository (with creating a SVN commit, etc.).
 - You could generate i18n text domains on the fly.
 

doc/ci/examples/semantic-release.md

@@ -126,7 +126,7 @@ Test the pipeline by creating a commit with a message like:
 fix: testing patch releases
 ```
 
-Push the commit to `master`. The pipeline should create a new release (`v1.0.0`) on the project's **Releases** page and publish a new version of the package to the project's **Package Registry** page.
+Push the commit to the default branch. The pipeline should create a new release (`v1.0.0`) on the project's **Releases** page and publish a new version of the package to the project's **Package Registry** page.
 
 To create a minor release, use a commit message like:
 

doc/ci/pipeline_editor/index.md

@@ -30,7 +30,7 @@ From the pipeline editor page you can:
 
 NOTE:
 You must already have [a `.gitlab-ci.yml` file](../quick_start/index.md#create-a-gitlab-ciyml-file)
-on the default branch (usually `master`) of your project to use the editor.
+on the default branch of your project to use the editor.
 
 ## Validate CI configuration
 

doc/ci/quick_start/index.md

@@ -66,7 +66,7 @@ In this file, you define:
 - The decisions the runner should make when specific conditions are encountered.
 
 For example, you might want to run a suite of tests when you commit to
-any branch except `master`. When you commit to `master`, you want
+any branch except the default branch. When you commit to the default branch, you want
 to run the same suite, but also publish your application.
 
 All of this is defined in the `.gitlab-ci.yml` file.

doc/ci/review_apps/index.md

@@ -31,8 +31,8 @@ In the above example:
 
 - A Review App is built every time a commit is pushed to `topic branch`.
 - The reviewer fails two reviews before passing the third review.
-- After the review has passed, `topic branch` is merged into `master` where it is deployed to staging.
-- After having been approved in staging, the changes that were merged into `master` are deployed in to production.
+- After the review passes, `topic branch` is merged into the default branch, where it's deployed to staging.
+- After its approval in staging, the changes that were merged into the default branch are deployed to production.
 
 ## How Review Apps work
 

doc/ci/troubleshooting.md

@@ -164,7 +164,7 @@ a branch to its remote repository. To illustrate the problem, suppose you've had
 
 1. A user creates a feature branch named `example` and pushes it to a remote repository.
 1. A new pipeline starts running on the `example` branch.
-1. A user rebases the `example` branch on the latest `master` branch and force-pushes it to its remote repository.
+1. A user rebases the `example` branch on the latest default branch and force-pushes it to its remote repository.
 1. A new pipeline starts running on the `example` branch again, however,
    the previous pipeline (2) fails because of `fatal: reference is not a tree:` error.
 

doc/ci/unit_test_reports.md

@@ -28,7 +28,7 @@ in the pipeline detail view.
 
 Consider the following workflow:
 
-1. Your `master` branch is rock solid, your project is using GitLab CI/CD and
+1. Your default branch is rock solid, your project is using GitLab CI/CD and
    your pipelines indicate that there isn't anything broken.
 1. Someone from your team submits a merge request, a test fails and the pipeline
    gets the known red icon. To investigate more, you have to go through the job
@@ -44,7 +44,7 @@ First, GitLab Runner uploads all [JUnit report format XML files](https://www.ibm
 as [artifacts](pipelines/job_artifacts.md#artifactsreportsjunit) to GitLab. Then, when you visit a merge request, GitLab starts
 comparing the head and base branch's JUnit report format XML files, where:
 
-- The base branch is the target branch (usually `master`).
+- The base branch is the target branch (usually the default branch).
 - The head branch is the source branch (the latest pipeline in each merge request).
 
 The reports panel has a summary showing how many tests failed, how many had errors

doc/ci/yaml/README.md

@@ -247,7 +247,7 @@ include:
 ```
 
 The [`MergeRequest-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml)
-makes your pipelines run for the default branch (usually `master`), tags, and
+makes your pipelines run for the default branch, tags, and
 all types of merge request pipelines. Use this template if you use any of the
 the [Pipelines for Merge Requests features](../merge_request_pipelines/), as mentioned
 above.
@@ -1260,9 +1260,9 @@ Other commonly used variables for `if` clauses:
 
 - `if: $CI_COMMIT_TAG`: If changes are pushed for a tag.
 - `if: $CI_COMMIT_BRANCH`: If changes are pushed to any branch.
-- `if: '$CI_COMMIT_BRANCH == "master"'`: If changes are pushed to `master`.
+- `if: '$CI_COMMIT_BRANCH == "main"'`: If changes are pushed to `main`.
 - `if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'`: If changes are pushed to the default
-  branch (usually `master`). Use when you want to have the same configuration in multiple
+  branch. Use when you want to have the same configuration in multiple
   projects with different default branches.
 - `if: '$CI_COMMIT_BRANCH =~ /regex-expression/'`: If the commit branch matches a regular expression.
 - `if: '$CUSTOM_VARIABLE !~ /regex-expression/'`: If the [custom variable](../variables/README.md#custom-cicd-variables)