Merge branch 'docs-ci-future-tense-2' into 'master'

Remove use of present tense in ci docs (part 2)

See merge request gitlab-org/gitlab!47987

doc/ci/migration/circleci.md

@@ -200,7 +200,7 @@ deploy_prod:
 
 ### Filter job by branch
 
-[Rules](../yaml/README.md#rules) are a mechanism to determine if the job will or will not run for a specific branch.
+[Rules](../yaml/README.md#rules) are a mechanism to determine if the job runs for a specific branch.
 
 CircleCI example of a job filtered by branch:
 

doc/ci/migration/jenkins.md

@@ -33,7 +33,7 @@ For an example of how to convert a Jenkins pipeline into a GitLab CI/CD pipeline
 or how to use Auto DevOps to test your code automatically, watch the
 [Migrating from Jenkins to GitLab](https://www.youtube.com/watch?v=RlEVGOpYF5Y) video.
 
-Otherwise, read on for important information that will help you get the ball rolling. Welcome
+Otherwise, read on for important information that helps you get the ball rolling. Welcome
 to GitLab!
 
 If you have questions that are not answered here, the [GitLab community forum](https://forum.gitlab.com/)
@@ -46,22 +46,22 @@ changes that comes with the move, and successfully managing them. There are a fe
 things we have found that helps this:
 
 - Setting and communicating a clear vision of what your migration goals are helps
-  your users understand why the effort is worth it. The value will be clear when
+  your users understand why the effort is worth it. The value is clear when
   the work is done, but people need to be aware while it's in progress too.
 - Sponsorship and alignment from the relevant leadership team helps with the point above.
 - Spending time educating your users on what's different, sharing this document with them,
-  and so on will help ensure you are successful.
+  and so on helps ensure you are successful.
 - Finding ways to sequence or delay parts of the migration can help a lot, but you
   don't want to leave things in a non-migrated (or partially-migrated) state for too
   long. To gain all the benefits of GitLab, moving your existing Jenkins setup over
-  as-is, including any current problems, will not be enough. You need to take advantage
+  as-is, including any current problems, isn't enough. You need to take advantage
   of the improvements that GitLab offers, and this requires (eventually) updating
   your implementation as part of the transition.
 
 ## JenkinsFile Wrapper
 
-We are building a [JenkinsFile Wrapper](https://gitlab.com/gitlab-org/jfr-container-builder/) which will allow
-you to run a complete Jenkins instance inside of a GitLab job, including plugins. This can help ease the process
+We are building a [JenkinsFile Wrapper](https://gitlab.com/gitlab-org/jfr-container-builder/) which
+you can use to run a complete Jenkins instance inside of a GitLab job, including plugins. This can help ease the process
 of transition, by letting you delay the migration of less urgent pipelines for a period of time.
 
 If you are interested in helping GitLab test the wrapper, join our [public testing issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215675) for instructions and to provide your feedback.
@@ -103,8 +103,8 @@ There are some high level differences between the products worth mentioning:
 - One important difference is that jobs run independently of each other and have a
   fresh environment in each job. Passing artifacts between jobs is controlled using the
   [`artifacts`](../yaml/README.md#artifacts) and [`dependencies`](../yaml/README.md#dependencies)
-  keywords. When finished, the planned [Workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/29265)
-  feature will allow you to more easily persist a common workspace between serial jobs.
+  keywords. When finished, use the planned [Workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/29265)
+  feature to more easily persist a common workspace between serial jobs.
 - The `.gitlab-ci.yml` file is checked in to the root of your repository, much like a Jenkinsfile, but
   is in the YAML format (see [complete reference](../yaml/README.md)) instead of a Groovy DSL. It's most
   analogous to the declarative Jenkinsfile format.
@@ -114,7 +114,7 @@ There are some high level differences between the products worth mentioning:
 - GitLab comes with a [container registry](../../user/packages/container_registry/index.md), and we recommend using
   container images to set up your build environment. For example, set up one pipeline that builds your build environment
   itself and publish that to the container registry. Then, have your pipelines use this instead of each building their
-  own environment, which will be slower and may be less consistent. We have extensive docs on [how to use the Container Registry](../../user/packages/container_registry/index.md).
+  own environment, which is slower and may be less consistent. We have extensive docs on [how to use the Container Registry](../../user/packages/container_registry/index.md).
 - A central utilities repository can be a great place to put assorted scheduled jobs
   or other manual jobs that function like utilities. Jenkins installations tend to
   have a few of these.
@@ -129,12 +129,12 @@ agents you were using.
 There are some important differences in the way runners work in comparison to agents:
 
 - Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/README.md#types-of-runners).
-  They will self-select jobs from the scopes you've defined automatically.
+  They self-select jobs from the scopes you've defined automatically.
 - You can also [use tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) for finer control, and
   associate runners with specific jobs. For example, you can use a tag for jobs that
   require dedicated, more powerful, or specific hardware.
-- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html)
-  which will let you configure them to be provisioned as needed, and scaled down when not.
+- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html).
+  Use autoscaling to provision runners only when needed, and scale down when not needed.
   This is similar to ephemeral agents in Jenkins.
 
 If you are using `gitlab.com`, you can take advantage of our [shared runner fleet](../../user/gitlab_com/index.md#shared-runners)
@@ -227,15 +227,15 @@ and is meant to be a mapping of concepts there to concepts in GitLab.
 
 #### `agent`
 
-The agent section is used to define how a pipeline will be executed. For GitLab, we use [runners](../runners/README.md)
+The agent section is used to define how a pipeline executes. For GitLab, we use [runners](../runners/README.md)
 to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage
-of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users.) The link above will bring you to the documentation which will describe how to get
-up and running quickly. We also support using [tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs
+of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users).
+We also support using [tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs
 to different runners (execution agents).
 
 The `agent` section also allows you to define which Docker images should be used for execution, for which we use
 the [`image`](../yaml/README.md#image) keyword. The `image` can be set on a single job or at the top level, in which
-case it will apply to all jobs in the pipeline:
+case it applies to all jobs in the pipeline:
 
 ```yaml
 my_job:
@@ -246,7 +246,7 @@ my_job:
 
 The `post` section defines the actions that should be performed at the end of the pipeline. GitLab also supports
 this through the use of stages. You can define your stages as follows, and any jobs assigned to the `before_pipeline`
-or `after_pipeline` stages will run as expected. You can call these stages anything you like:
+or `after_pipeline` stages run as expected. You can call these stages anything you like:
 
 ```yaml
 stages:

doc/ci/pipelines/pipeline_architectures.md

@@ -22,8 +22,8 @@ any of the keywords used below, check out our [CI YAML reference](../yaml/README
 
 ## Basic Pipelines
 
-This is the simplest pipeline in GitLab. It will run everything in the build stage concurrently,
-and once all of those finish, it will run everything in the test stage the same way, and so on.
+This is the simplest pipeline in GitLab. It runs everything in the build stage concurrently,
+and once all of those finish, it runs everything in the test stage the same way, and so on.
 It's not the most efficient, and if you have lots of steps it can grow quite complex, but it's
 easier to maintain:
 
@@ -101,7 +101,7 @@ your jobs. When GitLab knows the relationships between your jobs, it can run eve
 as fast as possible, and even skips into subsequent stages when possible.
 
 In the example below, if `build_a` and `test_a` are much faster than `build_b` and
-`test_b`, GitLab will start `deploy_a` even if `build_b` is still running.
+`test_b`, GitLab starts `deploy_a` even if `build_b` is still running.
 
 ```mermaid
 graph LR
@@ -163,7 +163,7 @@ deploy_b:
 
 In the examples above, it's clear we've got two types of things that could be built independently.
 This is an ideal case for using [Child / Parent Pipelines](../parent_child_pipelines.md)) via
-the [`trigger` keyword](../yaml/README.md#trigger). It will separate out the configuration
+the [`trigger` keyword](../yaml/README.md#trigger). It separates out the configuration
 into multiple files, keeping things very simple. You can also combine this with:
 
 - The [`rules` keyword](../yaml/README.md#rules): For example, have the child pipelines triggered only

doc/ci/quick_start/README.md

@@ -53,7 +53,7 @@ must [install GitLab Runner](https://docs.gitlab.com/runner/install/) and
 [register](https://docs.gitlab.com/runner/register/) at least one runner.
 
 If you are testing CI/CD, you can install GitLab Runner and register runners on your local machine.
-When your CI/CD jobs run, they will run on your local machine.
+When your CI/CD jobs run, they run on your local machine.
 
 ### Create a `.gitlab-ci.yml` file
 

doc/ci/ssh_keys/README.md

@@ -36,7 +36,7 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/)
    `~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys)
    if you are accessing a private GitLab repository.
 
-The private key will not be displayed in the job log, unless you enable
+The private key is displayed in the job log, unless you enable
 [debug logging](../variables/README.md#debug-logging). You might also want to
 check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines).
 
@@ -46,7 +46,7 @@ When your CI/CD jobs run inside Docker containers (meaning the environment is
 contained) and you want to deploy your code in a private server, you need a way
 to access it. This is where an SSH key pair comes in handy.
 
-1. You will first need to create an SSH key pair. For more information, follow
+1. You first need to create an SSH key pair. For more information, follow
    the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair).
    **Do not** add a passphrase to the SSH key, or the `before_script` will
    prompt for it.
@@ -144,9 +144,9 @@ For accessing repositories on GitLab.com, you would use `git@gitlab.com`.
 ## Verifying the SSH host keys
 
 It is a good practice to check the private server's own public key to make sure
-you are not being targeted by a man-in-the-middle attack. In case anything
-suspicious happens, you will notice it since the job would fail (the SSH
-connection would fail if the public keys would not match).
+you are not being targeted by a man-in-the-middle attack. If anything
+suspicious happens, you notice it because the job fails (the SSH
+connection fails when the public keys don't match).
 
 To find out the host keys of your server, run the `ssh-keyscan` command from a
 trusted network (ideally, from the private server itself):
@@ -169,8 +169,8 @@ TIP: **Tip:**
 By using a variable instead of `ssh-keyscan` directly inside
 `.gitlab-ci.yml`, it has the benefit that you don't have to change `.gitlab-ci.yml`
 if the host domain name changes for some reason. Also, the values are predefined
-by you, meaning that if the host keys suddenly change, the CI/CD job will fail,
-and you'll know there's something wrong with the server or the network.
+by you, meaning that if the host keys suddenly change, the CI/CD job doesn't fail,
+so there's something wrong with the server or the network.
 
 Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the
 [content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor)
@@ -209,4 +209,4 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available
 [shared runners](../runners/README.md).
 
 Want to hack on it? Simply fork it, commit and push your changes. Within a few
-moments the changes will be picked by a public runner and the job will begin.
+moments the changes is picked by a public runner and the job starts.

doc/ci/triggers/README.md

@@ -268,5 +268,5 @@ This behavior can also be achieved through GitLab's UI with
 Old triggers, created before GitLab 9.0 are marked as legacy.
 
 Triggers with the legacy label do not have an associated user and only have
-access to the current project. They are considered deprecated and will be
+access to the current project. They are considered deprecated and might be
 removed with one of the future versions of GitLab.

doc/ci/variables/deprecated_variables.md

@@ -17,7 +17,7 @@ To follow conventions of naming across GitLab, and to further move away from the
 release.
 
 Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are
-strongly advised to use the new variables as we will remove the old ones in
+strongly advised to use the new variables as we might remove the old ones in
 future GitLab releases.**
 
 | 8.x name              | 9.0+ name               |

doc/ci/variables/where_variables_can_be_used.md

@@ -57,8 +57,8 @@ There are three expansion mechanisms:
 ### GitLab internal variable expansion mechanism
 
 The expanded part needs to be in a form of `$variable`, or `${variable}` or `%variable%`.
-Each form is handled in the same way, no matter which OS/shell will finally handle the job,
-since the expansion is done in GitLab before any runner will get the job.
+Each form is handled in the same way, no matter which OS/shell handles the job,
+because the expansion is done in GitLab before any runner gets the job.
 
 ### GitLab Runner internal variable expansion mechanism
 
@@ -66,7 +66,7 @@ since the expansion is done in GitLab before any runner will get the job.
   variables from triggers, pipeline schedules, and manual pipelines.
 - Not supported: variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`).
 
-The runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle
+The runner uses Go's `os.Expand()` method for variable expansion. It means that it handles
 only variables defined as `$variable` and `${variable}`. What's also important, is that
 the expansion is done only once, so nested variables may or may not work, depending on the
 ordering of variables definitions.
@@ -77,7 +77,7 @@ This is an expansion that takes place during the `script` execution.
 How it works depends on the used shell (`bash`, `sh`, `cmd`, PowerShell). For example, if the job's
 `script` contains a line `echo $MY_VARIABLE-${MY_VARIABLE_2}`, it should be properly handled
 by bash/sh (leaving empty strings or some values depending whether the variables were
-defined or not), but will not work with Windows' `cmd` or PowerShell, since these shells
+defined or not), but don't work with Windows' `cmd` or PowerShell, since these shells
 are using a different variables syntax.
 
 Supported:
@@ -87,10 +87,10 @@ Supported:
   `.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules).
 - The `script` may also use all variables defined in the lines before. So, for example, if you define
   a variable `export MY_VARIABLE="test"`:
-  - In `before_script`, it will work in the following lines of `before_script` and
+  - In `before_script`, it works in the following lines of `before_script` and
     all lines of the related `script`.
-  - In `script`, it will work in the following lines of `script`.
-  - In `after_script`, it will work in following lines of `after_script`.
+  - In `script`, it works in the following lines of `script`.
+  - In `after_script`, it works in following lines of `after_script`.
 
 In the case of `after_script` scripts, they can:
 
@@ -133,7 +133,7 @@ due to security reasons.
 Variables defined with an environment scope are supported. Given that
 there is a variable `$STAGING_SECRET` defined in a scope of
 `review/staging/*`, the following job that is using dynamic environments
-is going to be created, based on the matching variable expression:
+is created, based on the matching variable expression:
 
 ```yaml
 my-job:

doc/ci/yaml/includes.md

@@ -67,7 +67,7 @@ include:
 
 ## Re-using a `before_script` template
 
-In the following example, the content of `.before-script-template.yml` will be
+In the following example, the content of `.before-script-template.yml` is
 automatically fetched and evaluated along with the content of `.gitlab-ci.yml`.
 
 Content of `https://gitlab.com/awesome-project/raw/master/.before-script-template.yml`: