diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-04-20 10:00:54 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-04-20 10:00:54 +0000 |
commit | 3cccd102ba543e02725d247893729e5c73b38295 (patch) | |
tree | f36a04ec38517f5deaaacb5acc7d949688d1e187 /doc/development/documentation | |
parent | 205943281328046ef7b4528031b90fbda70c75ac (diff) | |
download | gitlab-ce-3cccd102ba543e02725d247893729e5c73b38295.tar.gz |
Add latest changes from gitlab-org/gitlab@14-10-stable-eev14.10.0-rc42
Diffstat (limited to 'doc/development/documentation')
-rw-r--r-- | doc/development/documentation/feature_flags.md | 47 | ||||
-rw-r--r-- | doc/development/documentation/index.md | 3 | ||||
-rw-r--r-- | doc/development/documentation/restful_api_styleguide.md | 16 | ||||
-rw-r--r-- | doc/development/documentation/site_architecture/index.md | 2 | ||||
-rw-r--r-- | doc/development/documentation/styleguide/index.md | 173 | ||||
-rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 62 | ||||
-rw-r--r-- | doc/development/documentation/testing.md | 31 |
7 files changed, 191 insertions, 143 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 1e4698ff867..fb58851e93f 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -19,8 +19,29 @@ must be documented. For context, see the When you document feature flags, you must: -- [Add a note at the start of the topic](#use-a-note-to-describe-the-state-of-the-feature-flag). - [Add version history text](#add-version-history-text). +- [Add a note at the start of the topic](#use-a-note-to-describe-the-state-of-the-feature-flag). + +## Add version history text + +When the state of a flag changes (for example, disabled by default to enabled by default), add the change to the version history. + +Possible version history entries are: + +```markdown +> - [Introduced](issue-link) in GitLab X.X [with a flag](../../administration/feature_flags.md) named <flag name>. Disabled by default. +> - [Enabled on GitLab.com](issue-link) in GitLab X.X. +> - [Enabled on GitLab.com](issue-link) in GitLab X.X. Available to GitLab.com administrators only. +> - [Enabled on self-managed](issue-link) in GitLab X.X. +> - [Generally available](issue-link) in GitLab X.Y. [Feature flag <flag name>](issue-link) removed. +``` + +You can combine entries if they happened in the same release: + +```markdown +> - Introduced in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3. +``` ## Use a note to describe the state of the feature flag @@ -30,7 +51,8 @@ The note has three parts, and follows this structure: ```markdown FLAG: -<Self-managed GitLab availability information.> <GitLab.com availability information.> +<Self-managed GitLab availability information.> +<GitLab.com availability information.> <This feature is not ready for production use.> ``` @@ -61,27 +83,6 @@ If needed, you can add this sentence: `The feature is not ready for production use.` -## Add version history text - -When the state of a flag changes (for example, disabled by default to enabled by default), add the change to the version history. - -Possible version history entries are: - -```markdown -> - [Introduced](issue-link) in GitLab X.X [with a flag](../../administration/feature_flags.md) named <flag name>. Disabled by default. -> - [Enabled on GitLab.com](issue-link) in GitLab X.X. -> - [Enabled on GitLab.com](issue-link) in GitLab X.X. Available to GitLab.com administrators only. -> - [Enabled on self-managed](issue-link) in GitLab X.X. -> - [Generally available](issue-link) in GitLab X.Y. [Feature flag <flag name>](issue-link) removed. -``` - -You can combine entries if they happened in the same release: - -```markdown -> - Introduced in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3. -``` - ## Feature flag documentation examples The following examples show the progression of a feature flag. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 66d6beb821f..c6afcdbddd0 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -20,7 +20,7 @@ In addition to this page, the following resources can help you craft and contrib ## Source files and rendered web locations -Documentation for GitLab, GitLab Runner, Omnibus GitLab, and Charts is published to <https://docs.gitlab.com>. Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance. +Documentation for GitLab, GitLab Runner, GitLab Operator, Omnibus GitLab, and Charts is published to <https://docs.gitlab.com>. Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance. At `/help`, only help for your current edition and version is included. Help for other versions is available at <https://docs.gitlab.com/archives/>. The source of the documentation exists within the codebase of each GitLab application in the following repository locations: @@ -31,6 +31,7 @@ The source of the documentation exists within the codebase of each GitLab applic | [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) | | [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) | | [Charts](https://gitlab.com/gitlab-org/charts/gitlab) | [`/doc`](https://gitlab.com/gitlab-org/charts/gitlab/tree/master/doc) | +| [GitLab Operator](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator) | [`/doc`](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/tree/master/doc) | Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`. diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 4d654b6b901..8a505ed84a8 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -83,23 +83,25 @@ to describe the GitLab release that introduced the API call. Use the following table headers to describe the methods. Attributes should always be in code blocks using backticks (`` ` ``). -Sort the attributes in the table: first, required, then alphabetically. +Sort the table by required attributes first, then alphabetically. ```markdown | Attribute | Type | Required | Description | |:-----------------------------|:--------------|:-----------------------|:-----------------------------------------------------| -| `user` | string | **{check-circle}** Yes | The GitLab username. | -| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to. | -| `confidential` | boolean | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. | +| `title` | string | **{check-circle}** Yes | Title of the issue. | +| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. | +| `confidential` | boolean | **{dotted-circle}** No | Sets the issue to confidential. Default is `false`. | ``` Rendered example: | Attribute | Type | Required | Description | |:-----------------------------|:--------------|:-----------------------|:-----------------------------------------------------| -| `user` | string | **{check-circle}** Yes | The GitLab username. | -| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to. | -| `confidential` | boolean | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. | +| `title` | string | **{check-circle}** Yes | Title of the issue. | +| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. | +| `confidential` | boolean | **{dotted-circle}** No | Sets the issue to confidential. Default is `false`. | + +For information about writing attribute descriptions, see the [GraphQL API description style guide](../api_graphql_styleguide.md#description-style-guide). ## cURL commands diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index e7a915eab09..bdda15e2064 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -71,7 +71,7 @@ GitLab Docs is built with a combination of external: - [Schema.org](https://schema.org/) - [Google Analytics](https://marketingplatform.google.com/about/analytics/) -- [Google Tag Manager](https://developers.google.com/tag-manager/) +- [Google Tag Manager](https://developers.google.com/tag-platform/tag-manager) ## Global navigation diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 91e9d0c703d..7bfc0320d02 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -349,17 +349,15 @@ Follow these guidelines for punctuation: <!-- vale gitlab.Repetition = NO --> -| Rule | Example | -|------------------------------------------------------------------|--------------------------------------------------------| -| Avoid semicolons. Use two sentences instead. | That's the way that the world goes 'round. You're up one day and the next you're down. -| Always end full sentences with a period. | For a complete overview, read through this document. | -| Always add a space after a period when beginning a new sentence. | For a complete overview, check this doc. For other references, check out this guide. | -| Do not use double spaces. (Tested in [`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml).) | --- | -| Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- | -| Use serial commas (Oxford commas) before the final **and** or **or** in a list of three or more items. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | You can create new issues, merge requests, and milestones. | -| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | You should try this - or not. | -| When a colon is part of a sentence, always use lowercase after the colon. | Linked issues: a way to create a relationship between issues. | -| Do not use typographer's quotes. Use straight quotes instead. (Tested in [`NonStandardQuotes.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml).) | "It's the questions we can't answer that teach us the most"---Patrick Rothfuss | +- End full sentences with a period. +- Use one space between sentences. +- Do not use semicolons. Use two sentences instead. +- Do not use double spaces. (Tested in [`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml).) +- Do not use non-breaking spaces. Use standard spaces instead. (Tested in [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh).) +- Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. +- Use serial (Oxford) commas before the final **and** or **or** in a list of three or more items. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) +- Avoid dashes. Use separate sentences, or commas, instead. +- Do not use typographer's ("curly") quotes. Use straight quotes instead. (Tested in [`NonStandardQuotes.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml).) <!-- vale gitlab.Repetition = YES --> @@ -403,17 +401,6 @@ Backticks are more precise than quotes. For example, in this string: It's not clear whether the user should include the period in the string. -### Spaces between words - -Use only standard spaces between words. The search engine for the documentation -website doesn't split words separated with -[non-breaking spaces](https://en.wikipedia.org/wiki/Non-breaking_space) when -indexing, and fails to create expected individual search terms. Tests that search -for certain words separated by regular spaces can't find words separated by -non-breaking spaces. - -Tested in [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh). - ## Lists - Always start list items with a capital letter, unless they're parameters or @@ -421,30 +408,30 @@ Tested in [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scr - Always leave a blank line before and after a list. - Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). -### Ordered vs. unordered lists +### Choose between an ordered or unordered list -Only use ordered lists when their items describe a sequence of steps to follow. - -Do: +Use ordered lists for a sequence of steps. For example: ```markdown -These are the steps to do something: +Follow these steps to do something. 1. First, do the first step. 1. Then, do the next step. 1. Finally, do the last step. ``` -Don't: +Use an unordered lists when the steps do not need to be completed in order. For example: ```markdown -This is a list of available features: +These things are imported: -1. Feature 1 -1. Feature 2 -1. Feature 3 +- Thing 1 +- Thing 2 +- Thing 3 ``` +You can choose to introduce either list with a colon, but you do not have to. + ### Markup - Use dashes (`-`) for unordered lists instead of asterisks (`*`). @@ -454,12 +441,8 @@ This is a list of available features: ### Punctuation - Don't add commas (`,`) or semicolons (`;`) to the ends of list items. -- Only add periods to the end of a list item if the item consists of a complete - sentence (with a subject and a verb). -- Be consistent throughout the list: if the majority of the items do not end in - a period, do not end any of the items in a period, even if they consist of a - complete sentence. The opposite is also valid: if the majority of the items - end with a period, end all with a period. +- If a list item is a complete sentence (with a subject and a verb), add a period at the end. +- Majority rules. If the majority of items do not end in a period, do not end any of the items in a period. - Separate list items from explanatory text with a colon (`:`). For example: ```markdown @@ -469,32 +452,6 @@ This is a list of available features: - Second item: this explains the second item. ``` -**Examples:** - -Do: - -- First list item -- Second list item -- Third list item - -Don't: - -- First list item -- Second list item -- Third list item. - -Do: - -- Let's say this is a complete sentence. -- Let's say this is also a complete sentence. -- Not a complete sentence. - -Don't (vary use of periods; majority rules): - -- Let's say this is a complete sentence. -- Let's say this is also a complete sentence. -- Not a complete sentence - ### Nesting inside a list item It's possible to nest items under a list item, so that they render with the same @@ -686,7 +643,7 @@ For the heading text, **do not**: - Use words that might change in the future. Changing a heading changes its anchor URL, which affects other linked pages. - Repeat text from earlier headings. For example, instead of `Troubleshooting merge requests`, - use `Troubleshooting`. + use `Troubleshooting`. - Use links. ### Anchor links @@ -746,7 +703,7 @@ We include guidance for links in these categories: - Use inline link Markdown markup `[Text](https://example.com)`. It's easier to read, review, and maintain. Do not use `[Text][identifier]` reference-style links. -- Use [meaningful anchor text](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). +- Use meaningful anchor text. For example, instead of writing something like `Read more about merge requests [here](LINK)`, write `Read more about [merge requests](LINK)`. @@ -1561,6 +1518,47 @@ The voting strategy in GitLab 13.4 and later requires the primary and secondary voters to agree. ``` +#### Deprecated features + +When a feature is deprecated, add `(DEPRECATED)` to the page title or to +the heading of the section documenting the feature, immediately before +the tier badge: + +```markdown +<!-- Page title example: --> +# Feature A (DEPRECATED) **(ALL TIERS)** + +<!-- Doc section example: --> +## Feature B (DEPRECATED) **(PREMIUM SELF)** +``` + +Add the deprecation to the version history note (you can include a link +to a replacement when available): + +```markdown +> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). +``` + +You can also describe the replacement in surrounding text, if available. If the +deprecation isn't obvious in existing text, you may want to include a warning: + +```markdown +WARNING: +This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by +[Feature name](link-to-feature-documentation). +``` + +If you add `(DEPRECATED)` to the page's title and the document is linked from the docs +navigation, either remove the page from the nav or update the nav item to include the +same text before the feature name: + +```yaml + - doc_title: (DEPRECATED) Feature A +``` + +In the first major GitLab version after the feature was deprecated, be sure to +remove information about that deprecated feature. + #### End-of-life for features or products When a feature or product enters its end-of-life, indicate its status by @@ -1572,7 +1570,7 @@ For example: ```markdown WARNING: This feature is in its end-of-life process. It is [deprecated](link-to-issue) -for use in GitLab X.X, and is planned for [removal](link-to-issue) in GitLab X.X. +in GitLab X.X, and is planned for [removal](link-to-issue) in GitLab X.X. ``` After the feature or product is officially deprecated and removed, remove @@ -1647,47 +1645,6 @@ To view historical information about a feature, review GitLab [release posts](https://about.gitlab.com/releases/), or search for the issue or merge request where the work was done. -### Deprecated features - -When a feature is deprecated, add `(DEPRECATED)` to the page title or to -the heading of the section documenting the feature, immediately before -the tier badge: - -```markdown -<!-- Page title example: --> -# Feature A (DEPRECATED) **(ALL TIERS)** - -<!-- Doc section example: --> -## Feature B (DEPRECATED) **(PREMIUM SELF)** -``` - -Add the deprecation to the version history note (you can include a link -to a replacement when available): - -```markdown -> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). -``` - -You can also describe the replacement in surrounding text, if available. If the -deprecation isn't obvious in existing text, you may want to include a warning: - -```markdown -WARNING: -This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by -[Feature name](link-to-feature-documentation). -``` - -If you add `(DEPRECATED)` to the page's title and the document is linked from the docs -navigation, either remove the page from the nav or update the nav item to include the -same text before the feature name: - -```yaml - - doc_title: (DEPRECATED) Feature A -``` - -In the first major GitLab version after the feature was deprecated, be sure to -remove information about that deprecated feature. - ## Products and features Refer to the information in this section when describing products and features diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index c38c6586c3a..65f6a0a328b 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -97,6 +97,12 @@ The token generated when you create an agent for Kubernetes. Use **agent access - secret token - authentication token +## air gap, air-gapped + +Use **offline environment** to describe installations that have physical barriers or security policies that prevent or limit internet access. Do not use **air gap**, **air gapped**, or **air-gapped**. For example: + +- The firewall policies in an offline environment prevent the computer from accessing the internet. + ## allow, enable Try to avoid **allow** and **enable**, unless you are talking about security-related features. @@ -261,11 +267,17 @@ Do not use **Developer permissions**. A user who is assigned the Developer role See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance on **disable**. Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) - ## disallow Use **prevent** instead of **disallow**. ([Vale](../testing.md#vale) rule: [`Substitutions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Substitutions.yml)) +## downgrade + +To be more upbeat and precise, do not use **downgrade**. Focus instead on the action the user is taking. + +- For changing to earlier GitLab versions, use [**roll back**](#roll-back). +- For changing to lower GitLab tiers, use **change the subscription tier**. + ## dropdown list Use **dropdown list** to refer to the UI element. Do not use **dropdown** without **list** after it. @@ -729,12 +741,31 @@ Do not use **Reporter permissions**. A user who is assigned the Reporter role ha Use title case for **Repository Mirroring**. +## respectively + +Avoid **respectively** and be more precise instead. + +Use: + +- To create a user, select **Create user**. For an existing user, select **Save changes**. + +Instead of: + +- Select **Create user** or **Save changes** if you created a new user or + edited an existing one respectively. + ## roles Do not use **roles** and [**permissions**](#permissions) interchangeably. Each user is assigned a role. Each role includes a set of permissions. Roles are not the same as [**access levels**](#access-level). +## roll back + +Use **roll back** for changing a GitLab version to an earlier one. + +Do not use **roll back** for licensing or subscriptions. Use **change the subscription tier** instead. + ## runner, runners Use lowercase for **runners**. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). @@ -921,6 +952,33 @@ Use [**2FA** and **two-factor authentication**](#2fa-two-factor-authentication) Do not use **type** if you can avoid it. Use **enter** instead. +## update + +Use **update** for installing a newer **patch** version of the software only. For example: + +- Update GitLab from 14.9 to 14.9.1. + +Do not use **update** for any other case. Instead, use **upgrade**. + +## upgrade + +Use **upgrade** for: + +- Choosing a higher subscription tier (Premium or Ultimate). +- Installing a newer **major** (13.0, 14.0) or **minor** (13.8, 14.5) version of GitLab. + +For example: + +- Upgrade to GitLab Ultimate. +- Upgrade GitLab from 14.0 to 14.1. +- Upgrade GitLab from 14.0 to 15.0. + +Use caution with the phrase **Upgrade GitLab** without any other text. +Ensure the surrounding text clarifies whether +you're talking about the product version or the subscription tier. + +See also [downgrade](#downgrade) and [roll back](#roll-back). + ## useful Do not use **useful**. If the user doesn't find the process to be useful, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) @@ -971,7 +1029,7 @@ Do not use **yet** when talking about the product or its features. The documenta Sometimes you might need to use **yet** when writing a task. If you use **yet**, ensure the surrounding phrases are written -in present tense, active voice. +in present tense, active voice. [View guidance about how to write about future features](index.md#promising-features-in-future-versions). ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 49fe0aff3c6..9facb22669b 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -189,7 +189,7 @@ English language. Vale's configuration is stored in the [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) file located in the root directory of projects. -Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of +Vale supports creating [custom tests](https://docs.errata.ai/vale/styles) that extend any of several types of checks, which we store in the `.linting/vale/styles/gitlab` directory in the documentation directory of projects. @@ -365,6 +365,35 @@ file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. To set up `lefthook` for documentation linting, see [Pre-push static analysis](../contributing/style_guides.md#pre-push-static-analysis-with-lefthook). +#### Show Vale warnings on push + +By default, `lefthook` shows only Vale errors when pushing changes to a branch. The default branches +have no Vale errors, so any errors listed here are introduced by commits to the branch. + +To also see the Vale warnings when pushing to a branch, set a local environment variable: `VALE_WARNINGS=true`. + +Enable Vale warnings on push to improve the documentation suite by: + +- Detecting warnings you might be introducing with your commits. +- Identifying warnings that already exist in the page, which you can resolve to reduce technical debt. + +These warnings: + +- Don't stop the push from working. +- Don't result in a broken pipeline. +- Include all warnings for a file, not just warnings that are introduced by the commits. + +To enable Vale warnings on push: + +- Automatically, add `VALE_WARNINGS=true` to your shell configuration. +- Manually, prepend `VALE_WARNINGS=true` to invocations of `lefthook`. For example: + + ```shell + VALE_WARNINGS=true bundle exec lefthook run pre-push + ``` + +You can also [configure your editor](#configure-editors) to show Vale warnings. + ### Show subset of Vale alerts You can set Visual Studio Code to display only a subset of Vale alerts when viewing files: |