Commit 12d3a6f9 authored by 🤖 GitLab Bot 🤖's avatar 🤖 GitLab Bot 🤖
Browse files

Add latest changes from gitlab-org/gitlab@master

parent 07116000
---
name: allow_possible_spam
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17604
rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/29830
rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/33421
milestone: '12.4'
type: development
group: group::portfolio management
group: group::product planning
default_enabled: false
---
name: bulk_update_health_status
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33065
rollout_issue_url:
rollout_issue_url:
milestone: '13.2'
type: development
group: group::portfolio management
group: group::product planning
default_enabled: true
---
name: graphql_board_lists
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37905
rollout_issue_url:
rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/248908
milestone: '13.4'
type: development
group: group::project management
......
---
name: service_desk_custom_address
introduced_by_url:
rollout_issue_url:
milestone:
introduced_by_url:
rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/284656
milestone:
type: development
group: group::certify
default_enabled: false
......@@ -7,7 +7,7 @@
extends: existence
message: 'For consistency across all cURL examples, always wrap the URL in double quotes ("): %s'
link: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#curl-commands
level: warning
level: error
scope: code
raw:
- 'curl.*[^"=]https?://.*'
......@@ -8,6 +8,6 @@ extends: existence
message: 'Avoid words like "%s" that promise future changes, because documentation is about the current state of the product.'
level: suggestion
ignorecase: true
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#usage-list
tokens:
- currently
......@@ -9,7 +9,7 @@ extends: existence
message: 'Avoid using future tense: "%s". Use present tense instead.'
ignorecase: true
level: warning
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#usage-list
raw:
- "(going to( |\n|[[:punct:]])[a-zA-Z]*|"
- "will( |\n|[[:punct:]])[a-zA-Z]*|"
......
......@@ -8,7 +8,7 @@ extends: existence
message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.'
level: suggestion
ignorecase: true
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#usage-list
tokens:
- easy
- easily
......
......@@ -748,7 +748,7 @@ documentation](index.md#configure-gitaly-servers).
After all Gitaly nodes are configured, you can run the Praefect connection
checker to verify Praefect can connect to all Gitaly servers in the Praefect
config.
configuration.
1. SSH into each **Praefect** node and run the Praefect connection checker:
......
......@@ -137,7 +137,7 @@ store packages.
[Read more about using object storage with GitLab](../object_storage.md).
NOTE:
We recommend using the [consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). The following instructions apply to the original config format.
We recommend using the [consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). The following instructions apply to the original configuration format.
**Omnibus GitLab installations**
......
......@@ -204,7 +204,7 @@ control over how the Pages daemon runs and serves content in your environment.
| `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`.
| `auth_redirect_uri` | Callback URL for authenticating with GitLab. Defaults to project's subdomain of `pages_external_url` + `/auth`.
| `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration.
| `dir` | Working directory for config and secrets files.
| `dir` | Working directory for configuration and secrets files.
| `enable` | Enable or disable GitLab Pages on the current system.
| `external_http` | Configure Pages to bind to one or more secondary IP addresses, serving HTTP requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_http`.
| `external_https` | Configure Pages to bind to one or more secondary IP addresses, serving HTTPS requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_https`.
......@@ -241,7 +241,7 @@ control over how the Pages daemon runs and serves content in your environment.
| `pages_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`.
| `pages_nginx[]` | |
| `enable` | Include a virtual host `server{}` block for Pages inside NGINX. Needed for NGINX to proxy traffic back to the Pages daemon. Set to `false` if the Pages daemon should directly receive all requests, for example, when using [custom domains](index.md#custom-domains).
| `FF_ENABLE_REDIRECTS` | Feature flag to disable redirects (enabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#disable-redirects) for more info. |
| `FF_ENABLE_REDIRECTS` | Feature flag to disable redirects (enabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#disable-redirects) for more information. |
---
......
......@@ -395,7 +395,7 @@ API to check that the user is authorized to read that site.
From [GitLab 12.8](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3689) onward,
Access Control parameters for Pages are set in a configuration file, which
by convention is named `gitlab-pages-config`. The configuration file is passed to
pages using the `-config flag` or CONFIG environment variable.
pages using the `-config flag` or `CONFIG` environment variable.
Pages access control is disabled by default. To enable it:
......
......@@ -207,7 +207,7 @@ all Kubernetes resources and dependent charts:
helm get manifest <release name>
```
## Installation of minimal GitLab config via Minikube on macOS
## Installation of minimal GitLab configuration via Minikube on macOS
This section is based on [Developing for Kubernetes with Minikube](https://docs.gitlab.com/charts/development/minikube/index.html)
and [Helm](https://docs.gitlab.com/charts/installation/tools.html#helm). Refer
......
......@@ -23,7 +23,7 @@ on. Contributions are welcome to help add them.
## System Commands
### Distro Information
### Distribution Information
```shell
# Debian/Ubuntu
......@@ -200,7 +200,7 @@ or you can build it from source if you have the Rust compiler.
#### How to use the tool
First run the tool with no arguments other than the strace output file name to get
First run the tool with no arguments other than the strace output filename to get
a summary of the top processes sorted by time spent actively performing tasks. You
can also sort based on total time, # of syscalls made, PID #, and # of child processes
using the `-S` or `--sort` flag. The number of results defaults to 25 processes, but
......
......@@ -56,7 +56,7 @@ interested in.
### Getting the correlation ID from curl
If you're using `curl` then you can use the verbose option to show request and response headers, as well as other debug info.
If you're using `curl` then you can use the verbose option to show request and response headers, as well as other debug information.
```shell
➜ ~ curl --verbose "https://gitlab.example.com/api/v4/projects"
......
......@@ -2155,7 +2155,7 @@ POST /projects/:id/issues/:issue_iid/metric_images
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `issue_iid` | integer | yes | The internal ID of a project's issue |
| `file` | file | yes | The image file to be uploaded |
| `url` | string | no | The URL to view more metric info |
| `url` | string | no | The URL to view more metric information |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" --form 'file=@/path/to/file.png' \
......
......@@ -293,7 +293,7 @@ Example response:
```
NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: commits **(STARTER)**
......@@ -675,7 +675,7 @@ Example response:
```
NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: commits **(STARTER)**
......@@ -1072,7 +1072,7 @@ Example response:
```
NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: commits
......@@ -1146,7 +1146,7 @@ Example response:
```
NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: users
......
......@@ -93,7 +93,7 @@ too.
1. ✓ Redesign GitLab Pages configuration source to use GitLab's API
1. ✓ Evaluate performance and build reliable caching mechanisms
1. ✓ Incrementally rollout the new source on GitLab.com
1. ✓ Make GitLab Pages API domains config source enabled by default
1. ✓ Make GitLab Pages API domains configuration source enabled by default
1. Enable experimentation with different servings through feature flags
1. Triangulate object store serving design through meaningful experiments
1. Design pages migration mechanisms that can work incrementally
......
......@@ -14,7 +14,7 @@ GitLab CI/CD can be used with Bitbucket Cloud by:
To use GitLab CI/CD with a Bitbucket Cloud repository:
1. In GitLab create a **CI/CD for external repo**, select **Repo by URL** and
1. In GitLab create a **CI/CD for external repository**, select **Repo by URL** and
create the project.
![Create project](img/external_repository.png)
......
......@@ -35,7 +35,7 @@ repositories:
your project, update commit statuses, and create a web hook to notify
GitLab of new commits.
1. In GitLab, go to the [new project page](../../gitlab-basics/create-project.md#create-a-project-in-gitlab), select the **CI/CD for external repo** tab, and then click
1. In GitLab, go to the [new project page](../../gitlab-basics/create-project.md#create-a-project-in-gitlab), select the **CI/CD for external repository** tab, and then click
**GitHub**.
1. Paste the token into the **Personal access token** field and click **List
......
......@@ -26,7 +26,7 @@ snippets disabled. These features
To connect to an external repository:
1. From your GitLab dashboard, click **New project**.
1. Switch to the **CI/CD for external repo** tab.
1. Switch to the **CI/CD for external repository** tab.
1. Choose **GitHub** or **Repo by URL**.
1. The next steps are similar to the [import flow](../../user/project/import/index.md).
......
......@@ -629,7 +629,7 @@ Then every job that the runner picks up will be authenticated already. If you
are using the official `docker:19.03.13` image, the home directory is
under `/root`.
If you mount the config file, any `docker` command
If you mount the configuration file, any `docker` command
that modifies the `~/.docker/config.json` (for example, `docker login`)
fails, because the file is mounted as read-only. Do not change it from
read-only, because other problems will occur.
......@@ -703,7 +703,7 @@ There are multiple ways to define this. For example:
- Inside
[`pre_build_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section)
inside of the runner config file.
inside of the runner configuration file.
- Inside [`before_script`](../yaml/README.md#before_script).
- Inside of [`script`](../yaml/README.md#script).
......
......@@ -106,14 +106,10 @@ Guided Exploration project pipeline. It was tested on:
The example can be copied to your own group or instance for testing. More details
on what other GitLab CI patterns are demonstrated are available at the project page.
<!-- ## Troubleshooting
## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
### 403 error: "error checking push permissions"
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
If you receive this error, it might be due to an outside proxy. Setting the `http_proxy`
and `https_proxy` [environment variables](../../administration/packages/container_registry.md#running-the-docker-daemon-with-a-proxy)
can fix the problem.
......@@ -16,7 +16,7 @@ Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-deli
method.
All the code for this project can be found in this [GitLab
repo](https://gitlab.com/gitlab-examples/spring-gitlab-cf-deploy-demo).
repository](https://gitlab.com/gitlab-examples/spring-gitlab-cf-deploy-demo).
In case you're interested in deploying Spring Boot applications to Kubernetes
using GitLab CI/CD, read through the blog post [Continuous Delivery of a Spring Boot application with GitLab CI and Kubernetes](https://about.gitlab.com/blog/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/).
......
......@@ -421,7 +421,7 @@ fully understand [IAM Best Practices in AWS](https://docs.aws.amazon.com/IAM/lat
1. Go to your GitLab project, click **Settings > CI/CD** on the left sidebar
1. Expand the **Variables** section
![GitLab Secret Config](img/gitlab_config.png)
![GitLab Secret Configuration](img/gitlab_config.png)
1. Add a key named `AWS_KEY_ID` and copy the key ID from Step 2 into the **Value** field
1. Add a key named `AWS_KEY_SECRET` and copy the key secret from Step 2 into the **Value** field
......
......@@ -12,7 +12,7 @@ You can also view or fork the complete [example source](https://gitlab.com/gitla
## Initialize the module
1. Open a terminal and navigate to the project's repo
1. Open a terminal and navigate to the project's repository
1. Run `npm init`. Name the module according to [the Package Registry's naming conventions](../../user/packages/npm_registry/index.md#package-naming-convention). For example, if the project's path is `gitlab-examples/semantic-release-npm`, name the module `@gitlab-examples/semantic-release-npm`.
1. Install the following NPM packages:
......@@ -97,7 +97,7 @@ As part of publishing a package, semantic-release increases the version number i
## Configure semantic-release
semantic-release pulls its configuration info from a `.releaserc.json` file in the project. Create a `.releaserc.json` at the root of the repository:
semantic-release pulls its configuration information from a `.releaserc.json` file in the project. Create a `.releaserc.json` at the root of the repository:
```json
{
......
......@@ -79,7 +79,7 @@ To create a `.gitlab-ci.yml` file:
![New file](img/new_file_v13_6.png)
1. For the **File name** type `.gitlab-ci.yml` and in the larger window,
1. For the **Filename**, type `.gitlab-ci.yml` and in the larger window,
paste this sample code:
```yaml
......
......@@ -3283,6 +3283,11 @@ job1:
coverage: '/Code coverage: \d+\.\d+/'
```
The coverage is shown in the UI if at least one line in the job output matches the regular expression.
If there is more than one matched line in the job output, the last line is used.
For the matched line, the first occurence of `\d+(\.\d+)?` is the code coverage.
Leading zeros are removed.
### `retry`
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3442) in GitLab 9.5.
......
......@@ -20,11 +20,11 @@ configuration file and click on the `Visualization` tab. The visualization shows
all stages and jobs. [`needs`](README.md#needs) relationships are displayed as lines
connecting jobs together, showing the hierarchy of execution:
![CI Config Visualization](img/ci_config_visualization_v13_5.png)
![CI Configuration Visualization](img/ci_config_visualization_v13_5.png)
Hovering on a job highlights its `needs` relationships:
![CI Config Visualization on hover](img/ci_config_visualization_hover_v13_5.png)
![CI Configuration Visualization on hover](img/ci_config_visualization_hover_v13_5.png)
If the configuration does not have any `needs` relationships, then no lines are drawn because
each job depends only on the previous stage being completed successfully.
......
......@@ -10,7 +10,7 @@ GitLab community members and their privileges/responsibilities.
| Roles | Responsibilities | Requirements |
|-------|------------------|--------------|
| Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/company/team/). An expert on code reviews and knows the product/code base |
| Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/company/team/). An expert on code reviews and knows the product/codebase |
| Reviewer | Performs code reviews on MRs | Added to the [team page](https://about.gitlab.com/company/team/) |
| Developer |Has access to GitLab internal infrastructure & issues (e.g. HR-related) | GitLab employee or a Core Team member (with an NDA) |
| Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account |
......
......@@ -17,7 +17,7 @@ The `text` data type can not be defined with a limit, so `add_text_limit` is enf
adding a [check constraint](https://www.postgresql.org/docs/11/ddl-constraints.html) on the
column and then validating it at a followup step.
## Background info
## Background information
The reason we always want to use `text` instead of `string` is that `string` columns have the
disadvantage that if you want to update their limit, you have to run an `ALTER TABLE ...` command.
......@@ -256,7 +256,7 @@ end
To keep this guide short, we skipped the definition of the background migration and only
provided a high level example of the post-deployment migration that is used to schedule the batches.
You can find more info on the guide about [background migrations](../background_migrations.md)
You can find more information on the guide about [background migrations](../background_migrations.md)
#### Validate the text limit (next release)
......
......@@ -153,7 +153,7 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac
projects provide enough data to serve as a good example.
- That means that no query plan should return 0 records or less records than the provided limit (if a limit is included). If a query is used in batching, a proper example batch with adequate included results should be identified and provided.
- If your queries belong to a new feature in GitLab.com and thus they don't return data in production, it's suggested to analyze the query and to provide the plan from a local environment.
- More info on how to find the number of actual returned records in [Understanding EXPLAIN plans](understanding_explain_plans.md)
- More information on how to find the number of actual returned records in [Understanding EXPLAIN plans](understanding_explain_plans.md)
- For query changes, it is best to provide both the SQL queries along with the
plan _before_ and _after_ the change. This helps spot differences quickly.
- Include data that shows the performance improvement, preferably in
......
......@@ -14,7 +14,14 @@ Currently we rely on different sources to present diffs, these include:
## Deep Dive
In January 2019, Oswaldo Ferreira hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab's Diffs and Commenting on Diffs functionality to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=K6G3gMcFyek), and the slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/). Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may have changed since then, it should still serve as a good introduction.
In January 2019, Oswaldo Ferreira hosted a Deep Dive (GitLab team members only:
`https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab's Diffs and Commenting on Diffs
functionality to share his domain specific knowledge with anyone who may work in this part of the
codebase in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=K6G3gMcFyek),
and the slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit)
and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/).
Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may
have changed since then, it should still serve as a good introduction.
## Architecture overview
......
......@@ -253,7 +253,7 @@ available under `https://docs.gitlab.com/my-old-location/README.html` to a new l
`https://docs.gitlab.com/my-new-location/index.html`.
Into the **new document** front matter, we add the following information. You must
include the file name in the `disqus_identifier` URL, even if it's `index.html` or `README.html`.
include the filename in the `disqus_identifier` URL, even if it's `index.html` or `README.html`.
```yaml
---
......@@ -498,7 +498,7 @@ To run the tool on an existing screenshot generator, take the following steps:
1. Set up the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md).
1. Navigate to the subdirectory with your cloned GitLab repository, typically `gdk/gitlab`.
1. Make sure that your GDK database is fully migrated: `bin/rake db:migrate RAILS_ENV=development`.
1. Install pngquant, see the tool website for more info: [`pngquant`](https://pngquant.org/)
1. Install pngquant, see the tool website for more information: [`pngquant`](https://pngquant.org/)
1. Run `scripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>`.
1. Identify the location of the screenshots, based on the `gitlab/doc` location defined by the `it` parameter in your script.
1. Commit the newly created screenshots.
......
......@@ -39,7 +39,7 @@ pre-deployment and post-deployment tasks.
## Template for new docs
Follow the [folder structure and file name guidelines](styleguide/index.md#folder-structure-overview)
Follow the [folder structure and filename guidelines](styleguide/index.md#folder-structure-overview)
and create a new topic by using this template:
```markdown
......
......@@ -336,12 +336,6 @@ Only use the GitLab name and trademarks in accordance with
Don't use the possessive form of the word GitLab (`GitLab's`).
### Point of view
In most cases, it’s appropriate to use the second-person (you, yours) point of
view, because it’s friendly and easy to understand. (Tested in
[`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).)
### Capitalization
#### Headings
......@@ -529,84 +523,26 @@ You can use the following fake tokens as examples:
| Health check token | `Tu7BgjR9qeZTEyRzGG2P` |
| Request profile token | `7VgpS4Ax5utVD2esNstz` |
### Language to avoid
When creating documentation, limit or avoid the use of the following verb
tenses, words, and phrases:
- Avoid jargon when possible, and when not possible, define the term or
[link to a definition](#links-to-external-documentation).
- Avoid uncommon words when a more-common alternative is possible, ensuring that
content is accessible to more readers.
- Don't write in the first person singular.
(Tested in [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).)
<!-- vale gitlab.FirstPerson = NO -->
- Instead of _I_ or _me_, use _we_, _you_, _us_, or _one_.
<!-- vale gitlab.FirstPerson = YES -->
- When possible, stay user focused by writing in the second person (_you_ or
the imperative).
- Don't overuse "that". In many cases, you can remove "that" from a sentence
and improve readability.
- Avoid use of the future tense:
- Instead of `after you execute this command, GitLab will display the result`, use
`after you execute this command, GitLab displays the result`.
- Only use the future tense to convey when the action or result actually
occurs at a future time.
- Don't use slashes to clump different words together or as a replacement for
the word "or":
- Instead of "and/or," consider using "or," or use another sensible
construction.
- Other examples include "clone/fetch," author/assignee," and
"namespace/repository name." Break apart any such instances in an
appropriate way.
- Exceptions to this rule include commonly accepted technical terms, such as
CI/CD and TCP/IP.
<!-- vale gitlab.LatinTerms = NO -->
- We discourage the use of Latin abbreviations and terms, such as _e.g._,
_i.e._, _etc._, or _via_, as even native users of English can misunderstand
those terms. (Tested in [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml).)
- Instead of _i.e._, use _that is_.
- Instead of _via_, use _through_.
- Instead of _e.g._, use _for example_, _such as_, _for instance_, or _like_.
- Instead of _etc._, either use _and so on_ or consider editing it out, as
it can be vague.
<!-- vale gitlab.LatinTerms = YES -->
<!-- vale gitlab.CurrentStatus = NO -->
- Avoid using the word *currently* when talking about the product or its
features. The documentation describes the product as it is, and not as it
is planned to be in some indeterminate point in the future.
<!-- vale gitlab.CurrentStatus = YES -->
- Avoid using the word *scalability* when talking about increasing GitLab
performance for additional users. The words scale or scaling are sometimes
acceptable, but references to increasing GitLab performance for additional
users should direct readers to the GitLab
[reference architectures](../../../administration/reference_architectures/index.md)
page.
- Avoid all forms of the phrases *high availability* and *HA*, and instead
direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md)
for information about configuring GitLab to have the performance needed for
additional users over time.
- Don't use profanity or obscenities. Doing so may negatively affect other users
and contributors, which is contrary to the GitLab value of
[Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion).
- Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example:
- Use *primary* and *secondary* for database and server relationships.
- Use *allowlist* and *denylist* to describe access control lists.
- Avoid the word _please_. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please).
<!-- vale gitlab.Simplicity = NO -->
- Avoid words like _easily_, _simply_, _handy_, and _useful._ If the user
doesn't find the process to be these things, we lose their trust.
<!-- vale gitlab.Simplicity = YES -->
### Word usage clarifications
- Don't use "may" and "might" interchangeably:
- Use "might" to indicate the probability of something occurring. "If you
skip this step, the import process might fail."
- Use "may" to indicate giving permission for someone to do something, or
consider using "can" instead. "You may select either option on this
screen." Or, "You can select either option on this screen."
### Usage list
<!-- vale off -->
| Usage | Guidance | [Vale](../testing.md#vale) Tests |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| currently | Do not use when talking about the product or its features. The documentation describes the product as it is today. | None |
| e.g., i.e., via | Do not use Latin abbreviations.<br><br>- Instead of **e.g.**, use **for example**, **such as**, **for instance**, or **like**.<br>- Instead of **i.e.**, use **that is**.<br>- Instead of **via**, use **with**, **through**, or **by using**. | [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml) |
| future tense | When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. | [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml) |
| high availability, HA | Do not use. Direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab to have the performance needed for additional users over time. | None |
| I, me | Do not use first-person singular. Use **you**, **we**, or **us** instead. | [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml) |
| jargon | Do not use. Define the term or [link to a definition](#links-to-external-documentation). | None |
| may, might | **Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. | None |
| please | Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). | None |
| profanity | Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). | None |
| scalability | Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. | None |
| simply, easily, handy, useful | Do not use. If the user doesn't find the process to be these things, we lose their trust. | None |
| slashes | Instead of **and/or** use **or** or another sensible construction. This rule applies to other slashes as well, like **follow/unfollow**. Exception like **CI/CD** are allowed. | None |
| that | Do not use. Example: `the file that you save` can be `the file you save`. | None |