Add latest changes from gitlab-org/gitlab@master

app/graphql/types/award_emojis/award_emoji_type.rb

@@ -4,6 +4,7 @@ module Types
   module AwardEmojis
     class AwardEmojiType < BaseObject
       graphql_name 'AwardEmoji'
+      description 'An emoji awarded by a user.'
 
       authorize :read_emoji
 

doc/administration/geo/replication/datatypes.md

@@ -129,11 +129,11 @@ successfully, you must replicate their data using some other means.
 | Application data in PostgreSQL                      | **Yes**                  | **Yes**                     |                                             |
 | Project repository                                  | **Yes**                  | **Yes**                     |                                             |
 | Project wiki repository                             | **Yes**                  | **Yes**                     |                                             |
-| Project designs repository                          | **Yes**                  | [No][design-verification]   | Behind feature flag (*1*)                   |
-| Uploads                                             | **Yes**                  | [No][upload-verification]   | Verified only on transfer, or manually (*2*)|
-| LFS objects                                         | **Yes**                  | [No][lfs-verification]      | Verified only on transfer, or manually (*2*)|
-| CI job artifacts (other than traces)                | **Yes**                  | [No][artifact-verification] | Verified only manually (*2*)                |
-| Archived traces                                     | **Yes**                  | [No][artifact-verification] | Verified only on transfer, or manually (*2*)|
+| Project designs repository                          | **Yes**                  | [No][design-verification]   |                                             |
+| Uploads                                             | **Yes**                  | [No][upload-verification]   | Verified only on transfer, or manually (*1*)|
+| LFS objects                                         | **Yes**                  | [No][lfs-verification]      | Verified only on transfer, or manually (*1*)|
+| CI job artifacts (other than traces)                | **Yes**                  | [No][artifact-verification] | Verified only manually (*1*)                |
+| Archived traces                                     | **Yes**                  | [No][artifact-verification] | Verified only on transfer, or manually (*1*)|
 | Personal snippets                                   | **Yes**                  | **Yes**                     |                                             |
 | Project snippets                                    | **Yes**                  | **Yes**                     |                                             |
 | Object pools for forked project deduplication       | **Yes**                  | No                          |                                             |
@@ -147,13 +147,7 @@ successfully, you must replicate their data using some other means.
 | [External merge request diffs][merge-request-diffs] | [No][diffs-replication]  | No                          |                                             |
 | Content in object storage                           | **Yes**                  | No                          |                                             |
 
-- (*1*): Enable the `enable_geo_design_sync` feature flag by running the following in a Rails console:
-
-  ```ruby
-  Feature.disable(:enable_geo_design_sync)
-  ```
-
-- (*2*): The integrity can be verified manually using
+- (*1*): The integrity can be verified manually using
   [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them.
 
 [design-replication]: https://gitlab.com/groups/gitlab-org/-/epics/1633

doc/administration/job_artifacts.md

@@ -294,3 +294,149 @@ memory and disk I/O.
 [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab"
 [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab"
 [gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository"
+
+## Troubleshooting
+
+### Job artifacts using too much disk space
+
+Job artifacts can fill up your disk space quicker than expected. Some possible
+reasons are:
+
+- Users have configured job artifacts expiration to be longer than necessary.
+- The number of jobs run, and hence artifacts generated, is higher than expected.
+- Job logs are larger than expected, and have accumulated over time.
+
+In these and other cases, you'll need to identify the projects most responsible
+for disk space usage, figure out what types of artifacts are using the most
+space, and in some cases, manually delete job artifacts to reclaim disk space.
+
+#### List projects by total size of job artifacts stored
+
+List the top 20 projects, sorted by the total size of job artifacts stored, by
+running the following code in the Rails console (`sudo gitlab-rails console`):
+
+```ruby
+include ActionView::Helpers::NumberHelper
+ProjectStatistics.order(build_artifacts_size: :desc).limit(20).each do |s|
+  puts "#{number_to_human_size(s.build_artifacts_size)} \t #{s.project.full_path}"
+end
+```
+
+You can change the number of projects listed by modifying `.limit(20)` to the
+number you want.
+
+#### List largest artifacts in a single project
+
+List the 50 largest job artifacts in a single project by running the following
+code in the Rails console (`sudo gitlab-rails console`):
+
+```ruby
+include ActionView::Helpers::NumberHelper
+project = Project.find_by_full_path('path/to/project')
+Ci::JobArtifact.where(project: project).order(size: :desc).limit(50).map { |a| puts "ID: #{a.id} - #{a.file_type}: #{number_to_human_size(a.size)}" }
+```
+
+You can change the number of job artifacts listed by modifying `.limit(50)` to
+the number you want.
+
+#### Delete job artifacts from jobs completed before a specific date
+
+CAUTION: **CAUTION:**
+These commands remove data permanently from the database and from disk. We
+highly recommend running them only under the guidance of a Support Engineer, or
+running them in a test environment with a backup of the instance ready to be
+restored, just in case.
+
+If you need to manually remove job artifacts associated with multiple jobs while
+**retaining their job logs**, this can be done from the Rails console (`sudo gitlab-rails console`):
+
+1. Select jobs to be deleted:
+
+   To select all jobs with artifacts for a single project:
+
+   ```ruby
+   project = Project.find_by_full_path('path/to/project')
+   builds_with_artifacts =  project.builds.with_artifacts_archive
+   ```
+
+   To select all jobs with artifacts across the entire GitLab instance:
+
+   ```ruby
+   builds_with_artifacts = Ci::Build.with_artifacts_archive
+   ```
+
+1. Delete job artifacts older than a specific date:
+
+   NOTE: **NOTE:**
+   This step will also erase artifacts that users have chosen to
+   ["keep"](../user/project/pipelines/job_artifacts.html#browsing-artifacts).
+
+   ```ruby
+   builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago)
+   builds_to_clear.find_each do |build|
+     build.artifacts_expire_at = Time.now
+     build.erase_erasable_artifacts!
+   end
+   ```
+
+   `1.week.ago` is a Rails `ActiveSupport::Duration` method which calculates a new
+   date or time in the past. Other valid examples are:
+
+   - `7.days.ago`
+   - `3.months.ago`
+   - `1.year.ago`
+
+#### Delete job artifacts and logs from jobs completed before a specific date
+
+CAUTION: **CAUTION:**
+These commands remove data permanently from the database and from disk. We
+highly recommend running them only under the guidance of a Support Engineer, or
+running them in a test environment with a backup of the instance ready to be
+restored, just in case.
+
+If you need to manually remove ALL job artifacts associated with multiple jobs,
+**including job logs**, this can be done from the Rails console (`sudo gitlab-rails console`):
+
+1. Select jobs to be deleted:
+
+   To select jobs with artifacts for a single project:
+
+   ```ruby
+   project = Project.find_by_full_path('path/to/project')
+   builds_with_artifacts =  project.builds.with_existing_job_artifacts
+   ```
+
+   To select jobs with artifacts across the entire GitLab instance:
+
+   ```ruby
+   builds_with_artifacts = Ci::Build.with_existing_job_artifacts
+   ```
+
+1. Select the user which will be mentioned in the web UI as erasing the job:
+
+   ```ruby
+   admin_user = User.find_by(username: 'username')
+   ```
+
+1. Erase job artifacts and logs older than a specific date:
+
+   ```ruby
+   builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago)
+   builds_to_clear.find_each do |build|
+     print "Ci::Build ID #{build.id}... "
+
+     if build.erasable?
+       build.erase(erased_by: admin_user)
+       puts "Erased"
+     else
+       puts "Skipped (Nothing to erase or not erasable)"
+     end
+   end
+   ```
+
+   `1.week.ago` is a Rails `ActiveSupport::Duration` method which calculates a new
+   date or time in the past. Other valid examples are:
+
+   - `7.days.ago`
+   - `3.months.ago`
+   - `1.year.ago`

doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md

@@ -743,6 +743,8 @@ Namespace.find_by_full_path("user/proj").namespace_statistics.update(shared_runn
 
 ### Remove artifacts more than a week old
 
+The Latest version of these steps can be found in the [job artifacts documentation](../job_artifacts.md)
+
 ```ruby
 ### SELECTING THE BUILDS TO CLEAR
 # For a single project:

doc/api/graphql/reference/gitlab_schema.graphql

@@ -38,6 +38,9 @@ type AddAwardEmojiPayload {
   errors: [String!]!
 }
 
+"""
+An emoji awarded by a user.
+"""
 type AwardEmoji {
   """
   The emoji description
@@ -529,6 +532,9 @@ type CreateSnippetPayload {
   snippet: Snippet
 }
 
+"""
+A single design
+"""
 type Design implements DesignFields & Noteable {
   """
   The diff refs for this design
@@ -651,6 +657,9 @@ type Design implements DesignFields & Noteable {
   ): DesignVersionConnection!
 }
 
+"""
+A collection of designs.
+"""
 type DesignCollection {
   """
   All designs for the design collection
@@ -979,7 +988,7 @@ type DesignVersionEdge {
 }
 
 """
-Mutation event of a Design within a Version
+Mutation event of a design within a version
 """
 enum DesignVersionEvent {
   """
@@ -1403,6 +1412,9 @@ enum EntryType {
   tree
 }
 
+"""
+Represents an epic.
+"""
 type Epic implements Noteable {
   """
   Author of the epic
@@ -1761,6 +1773,9 @@ type EpicConnection {
   pageInfo: PageInfo!
 }
 
+"""
+Counts of descendent epics.
+"""
 type EpicDescendantCount {
   """
   Number of closed sub-epics
@@ -1798,6 +1813,9 @@ type EpicEdge {
   node: Epic
 }
 
+"""
+Relationship between an epic and an issue
+"""
 type EpicIssue implements Noteable {
   """
   Assignees of the issue
@@ -2246,7 +2264,7 @@ enum EpicSort {
 }
 
 """
-State of a GitLab epic
+State of an epic.
 """
 enum EpicState {
   all
@@ -2255,20 +2273,23 @@ enum EpicState {
 }
 
 """
-State event of a GitLab Epic
+State event of an epic
 """
 enum EpicStateEvent {
   """
-  Close the Epic
+  Close the epic
   """
   CLOSE
 
   """
-  Reopen the Epic
+  Reopen the epic
   """
   REOPEN
 }
 
+"""
+A node of an epic tree.
+"""
 input EpicTreeNodeFieldsInputType {
   """
   The id of the epic_issue or issue that the actual epic or issue is switched with

doc/api/graphql/reference/gitlab_schema.json

@@ -3695,7 +3695,7 @@
         {
           "kind": "OBJECT",
           "name": "Epic",
-          "description": null,
+          "description": "Represents an epic.",
           "fields": [
             {
               "name": "author",
@@ -7384,7 +7384,7 @@
         {
           "kind": "ENUM",
           "name": "EpicState",
-          "description": "State of a GitLab epic",
+          "description": "State of an epic.",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
@@ -8009,7 +8009,7 @@
         {
           "kind": "OBJECT",
           "name": "EpicIssue",
-          "description": null,
+          "description": "Relationship between an epic and an issue",
           "fields": [
             {
               "name": "assignees",
@@ -9230,7 +9230,7 @@
         {
           "kind": "OBJECT",
           "name": "DesignCollection",
-          "description": null,
+          "description": "A collection of designs.",
           "fields": [
             {
               "name": "designs",
@@ -10346,7 +10346,7 @@
         {
           "kind": "OBJECT",
           "name": "Design",
-          "description": null,
+          "description": "A single design",
           "fields": [
             {
               "name": "diffRefs",
@@ -10880,7 +10880,7 @@
         {
           "kind": "ENUM",
           "name": "DesignVersionEvent",
-          "description": "Mutation event of a Design within a Version",
+          "description": "Mutation event of a design within a version",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
@@ -11133,7 +11133,7 @@
         {
           "kind": "OBJECT",
           "name": "EpicDescendantCount",
-          "description": null,
+          "description": "Counts of descendent epics.",
           "fields": [
             {
               "name": "closedEpics",
@@ -16943,7 +16943,7 @@
         {
           "kind": "OBJECT",
           "name": "AwardEmoji",
-          "description": null,
+          "description": "An emoji awarded by a user.",
           "fields": [
             {
               "name": "description",
@@ -20689,7 +20689,7 @@
         {
           "kind": "INPUT_OBJECT",
           "name": "EpicTreeNodeFieldsInputType",
-          "description": null,
+          "description": "A node of an epic tree.",
           "fields": null,
           "inputFields": [
             {
@@ -20987,20 +20987,20 @@
         {
           "kind": "ENUM",
           "name": "EpicStateEvent",
-          "description": "State event of a GitLab Epic",
+          "description": "State event of an epic",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
           "enumValues": [
             {
               "name": "REOPEN",
-              "description": "Reopen the Epic",
+              "description": "Reopen the epic",
               "isDeprecated": false,
               "deprecationReason": null
             },
             {
               "name": "CLOSE",
-              "description": "Close the Epic",
+              "description": "Close the epic",
               "isDeprecated": false,
               "deprecationReason": null
             }

doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md

@@ -26,7 +26,7 @@ Creating a strong CI/CD pipeline at the beginning of developing another game, [D
 was essential for the fast pace the team worked at. This tutorial will build upon my
 [previous introductory article](https://ryanhallcs.wordpress.com/2017/03/15/devops-and-game-dev/) and go through the following steps:
 
-1. Using code from the previous article to start with a barebones [Phaser](https://phaser.io) game built by a gulp file
+1. Using code from the previous article to start with a bare-bones [Phaser](https://phaser.io) game built by a gulp file
 1. Adding and running unit tests
 1. Creating a `Weapon` class that can be triggered to spawn a `Bullet` in a given direction
 1. Adding a `Player` class that uses this weapon and moves around the screen

doc/development/documentation/index.md

@@ -208,7 +208,7 @@ available online on 2018-09-15, but, as the feature freeze date has passed, if
 the MR does not have a "pick into 11.3" label, the milestone has to be changed
 to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22,
 with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab
-11.4 onwards, but available on <https://docs.gitlab.com/> on the same day it was merged.
+11.4 onward, but available on <https://docs.gitlab.com/> on the same day it was merged.
 
 ### Linking to `/help`
 

doc/development/merge_request_performance_guidelines.md

@@ -93,7 +93,7 @@ the following:
 The query plan can answer the questions whether we need additional
 indexes, or whether we perform expensive filtering (i.e. using sequential scans).
 
-Each query plan should be run against substantional size of data set.
+Each query plan should be run against substantial size of data set.
 For example if you look for issues with specific conditions,
 you should consider validating the query against
 a small number (a few hundred) and a big number (100_000) of issues.
@@ -318,7 +318,7 @@ Take into consideration the following when choosing a pagination strategy:
 
 1. It is very inefficient to calculate amount of objects that pass the filtering,
    this operation usually can take seconds, and can time out,
-1. It is very inefficent to get entries for page at higher ordinals, like 1000.
+1. It is very inefficient to get entries for page at higher ordinals, like 1000.
    The database has to sort and iterate all previous items, and this operation usually
    can result in substantial load put on database.
 
@@ -363,7 +363,7 @@ The intent of quotas could be different:
 
 1. We want to provide higher quotas for higher tiers of features:
    we want to provide on GitLab.com more capabilities for different tiers,
-1. We want to prevent misuse of the feature: someone accidentially creates
+1. We want to prevent misuse of the feature: someone accidentally creates
    10000 deploy tokens, because of a broken API script,
 1. We want to prevent abuse of the feature: someone purposely creates
    a 10000 pipelines to take advantage of the system.
@@ -374,7 +374,7 @@ Examples:
    more than 50 schedules.
    In such cases it is rather expected that this is either misuse
    or abuse of the feature. Lack of the upper limit can result
-   in service degredation as the system will try to process all schedules
+   in service degradation as the system will try to process all schedules
    assigned the the project.
 
 1. GitLab CI includes: We started with the limit of maximum of 50 nested includes.

doc/development/migration_style_guide.md

@@ -323,7 +323,7 @@ In this particular case, the default value exists and we're just changing the me
 in the `namespaces` table. Only when creating a new column with a default, all the records are going be rewritten.
 
 NOTE: **Note:**  A faster [ALTER TABLE ADD COLUMN with a non-null default](https://www.depesz.com/2018/04/04/waiting-for-postgresql-11-fast-alter-table-add-column-with-a-non-null-default/)
-was introduced on PostgresSQL 11.0, removing the need of rewritting the table when a new column with a default value is added.
+was introduced on PostgresSQL 11.0, removing the need of rewriting the table when a new column with a default value is added.
 
 For the reasons mentioned above, it's safe to use `change_column_default` in a single-transaction migration
 without requiring `disable_ddl_transaction!`.

doc/development/pipelines.md

@@ -132,11 +132,11 @@ for the list of exact patterns.**
 ## Rules conditions and changes patterns
 
 We're making use of the [`rules` keyword](https://docs.gitlab.com/ee/ci/yaml/#rules) but we're currently
-duplicating the `if` conditions and `changes` patterns lists since they cannot be shared accross
+duplicating the `if` conditions and `changes` patterns lists since they cannot be shared across
 `include`d files as we do with `extends`.
 
 **If you update an `if` condition or `changes`
-patterns list, make sure to mass-update those accross all the CI config files (i.e. `.gitlab/ci/*.yml`).**
+patterns list, make sure to mass-update those across all the CI config files (i.e. `.gitlab/ci/*.yml`).**
 
 ### Canonical commits only
 

doc/development/testing_guide/best_practices.md

@@ -67,7 +67,7 @@ When using spring and guard together, use `SPRING=1 bundle exec guard` instead t
 - Don't supply the `:each` argument to hooks since it's the default.
 - On `before` and `after` hooks, prefer it scoped to `:context` over `:all`
 - When using `evaluate_script("$('.js-foo').testSomething()")` (or `execute_script`) which acts on a given element,
-  use a Capyabara matcher beforehand (e.g. `find('.js-foo')`) to ensure the element actually exists.
+  use a Capybara matcher beforehand (e.g. `find('.js-foo')`) to ensure the element actually exists.
 - Use `focus: true` to isolate parts of the specs you want to run.
 - Use [`:aggregate_failures`](https://relishapp.com/rspec/rspec-core/docs/expectation-framework-integration/aggregating-failures) when there is more than one expectation in a test.
 - For [empty test description blocks](https://github.com/rubocop-hq/rspec-style-guide#it-and-specify), use `specify` rather than `it do` if the test is self-explanatory.

doc/development/testing_guide/end_to_end/best_practices.md

@@ -14,7 +14,7 @@ Now, realize that almost all tests need the user to be logged in, and that we ne
 
 Now, multiply the number of tests per 2 seconds, and as your test suite grows, the time to run it grows with it, and this is not sustainable.
 
-An alternative to perform a login in a cheaper way would be having an endpoint (available only for testing) where we could pass the user's credentials as encrypted values as query strings, and then we would be redirected to the logged in home page if the credentials are valid. Let's say that, on average, this process takes only 200 miliseconds.
+An alternative to perform a login in a cheaper way would be having an endpoint (available only for testing) where we could pass the user's credentials as encrypted values as query strings, and then we would be redirected to the logged in home page if the credentials are valid. Let's say that, on average, this process takes only 200 milliseconds.
 
 You see the point right?
 

doc/development/testing_guide/end_to_end/quick_start_guide.md

@@ -445,7 +445,7 @@ end
 
 By defining the `resource_web_url(resource)` method, we override the one from the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab/blob/master/qa/qa/resource/api_fabricator.rb#L44) module. We do that to avoid failing the test due to this particular resource not exposing a `web_url` property.
 
-By defining the `api_get_path` method, we **would** allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to get a single label, but since there's no path available for that in the publich API, we raise a `NotImplementedError` instead.
+By defining the `api_get_path` method, we **would** allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to get a single label, but since there's no path available for that in the public API, we raise a `NotImplementedError` instead.
 
 By defining the `api_post_path` method, we allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to create a new label in a specific project.
 

doc/development/testing_guide/flaky_tests.md

@@ -76,7 +76,7 @@ This was originally implemented in: <https://gitlab.com/gitlab-org/gitlab-foss/m
 
 ### Feature tests
 
-- [Be sure to create all the data the test need before starting exercize](https://gitlab.com/gitlab-org/gitlab-foss/issues/32622#note_31128195): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12059>
+- [Be sure to create all the data the test need before starting exercise](https://gitlab.com/gitlab-org/gitlab-foss/issues/32622#note_31128195): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12059>
 - [Bis](https://gitlab.com/gitlab-org/gitlab-foss/issues/34609#note_34048715): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12604>
 - [Bis](https://gitlab.com/gitlab-org/gitlab-foss/issues/34698#note_34276286): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12664>
 - [Assert against the underlying database state instead of against a page's content](https://gitlab.com/gitlab-org/gitlab-foss/issues/31437): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/10934>

doc/development/testing_guide/frontend_testing.md

@@ -315,7 +315,7 @@ export, one is be generated by the babel plugin). The second parameter is the
 name of the import you wish to change. The result of the function is a Spy
 object which can be treated like any other Jasmine spy object.
 
-Further documentation on the babel rewire pluign API can be found on
+Further documentation on the babel rewire plugin API can be found on
 [its repository Readme doc](https://github.com/speedskater/babel-plugin-rewire#babel-plugin-rewire).
 
 #### Waiting in tests
@@ -532,7 +532,7 @@ In order to ensure that a clean wrapper object and DOM are being used in each te
   });
 ```
 
-See also the [Vue Test Utils documention on `destroy`](https://vue-test-utils.vuejs.org/api/wrapper/#destroy).
+See also the [Vue Test Utils documentation on `destroy`](https://vue-test-utils.vuejs.org/api/wrapper/#destroy).
 
 #### Migrating flaky Karma tests to Jest
 
@@ -649,7 +649,7 @@ it('uses some HTML element', () => {
 HTML and JSON fixtures are generated from backend views and controllers using RSpec (see `spec/frontend/fixtures/*.rb`).
 
 For each fixture, the content of the `response` variable is stored in the output file.
-This variable gets automagically set if the test is marked as `type: :request` or `type: :controller`.
+This variable gets automatically set if the test is marked as `type: :request` or `type: :controller`.
 Fixtures are regenerated using the `bin/rake frontend:fixtures` command but you can also generate them individually,
 for example `bin/rspec spec/frontend/fixtures/merge_requests.rb`.
 When creating a new fixture, it often makes sense to take a look at the corresponding tests for the endpoint in `(ee/)spec/controllers/` or `(ee/)spec/requests/`.

doc/integration/elasticsearch.md

@@ -600,7 +600,7 @@ Here are some common pitfalls and how to overcome them:
   **For a single node Elasticsearch cluster the functional cluster health status will be yellow** (will never be green) because the primary shard is allocated but replicas can not be as there is no other node to which Elasticsearch can assign a replica. This also applies if you are using using the
 [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-handling-errors.html#aes-handling-errors-yellow-cluster-status) service.
 
-  CAUTION: **Warning**: Setting the number of replicas to `0` is not something that we recommend (this is not allowed in the GitLab Elasticsearch Integration menu). If you are planning to add more Elasticsearch nodes (for a total of more than 1 Elasticsearch) the number of replicas will need to be set to an integer value larger than `0`. Failure to do so will result in lack of redundancy (losing one node will corupt the index).
+  CAUTION: **Warning**: Setting the number of replicas to `0` is not something that we recommend (this is not allowed in the GitLab Elasticsearch Integration menu). If you are planning to add more Elasticsearch nodes (for a total of more than 1 Elasticsearch) the number of replicas will need to be set to an integer value larger than `0`. Failure to do so will result in lack of redundancy (losing one node will corrupt the index).
 
   If you have a **hard requirement to have a green status for your single node Elasticsearch cluster**, please make sure you understand the risks outlined in the previous paragraph and then simply run the following query to set the number of replicas to `0`(the cluster will no longer try to create any shard replicas):
 

doc/integration/jira_development_panel.md

@@ -100,7 +100,7 @@ There are no special requirements if you are using GitLab.com.
    every 60 minutes.
 
    > **Note:**
-   > In the future, we plan on implementating real-time integration. If you need
+   > In the future, we plan on implementing real-time integration. If you need
    > to refresh the data manually, you can do this from the `Applications -> DVCS
    > accounts` screen where you initially set up the integration:
    >

doc/integration/kerberos.md

@@ -265,7 +265,7 @@ so the client will fall back to attempting to negotiate `IAKERB`, leading to the
 above error message.
 
 To fix this, ensure that the forward and reverse DNS for your GitLab server
-match. So for instance, if you acces GitLab as `gitlab.example.com`, resolving
+match. So for instance, if you access GitLab as `gitlab.example.com`, resolving
 to IP address `1.2.3.4`, then `4.3.2.1.in-addr.arpa` must be a PTR record for
 `gitlab.example.com`.
 

doc/integration/sourcegraph.md

@@ -100,7 +100,7 @@ When visiting one of these views, you can now hover over a code reference to see
 
 - Details on how this reference was defined.
 - **Go to definition**, which navigates to the line of code where this reference was defined.
-- **Find references**, which navigates to the configured Sourcegraph instance, showing a list of references to the hilighted code.
+- **Find references**, which navigates to the configured Sourcegraph instance, showing a list of references to the highlighted code.
 
 ![Sourcegraph demo](img/sourcegraph_popover_v12_5.png)
 

doc/security/webhooks.md

@@ -60,7 +60,7 @@ and expand **Outbound requests**:
 
 ![Outbound local requests whitelist](img/whitelist.png)
 
-The whilelist entries can be separated by semicolons, commas or whitespaces
+The whitelist entries can be separated by semicolons, commas or whitespaces
 (including newlines) and be in different formats like hostnames, IP addresses and/or
 IP ranges. IPv6 is supported. Hostnames that contain unicode characters should
 use IDNA encoding.

doc/topics/autodevops/quick_start_guide.md

@@ -30,7 +30,7 @@ Google Kubernetes Engine Integration. All you have to do is [follow this link](h
 ## Creating a new project from a template
 
 We will use one of GitLab's project templates to get started. As the name suggests,
-those projects provide a barebones application built on some well-known frameworks.
+those projects provide a bare-bones application built on some well-known frameworks.
 
 1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select
    **New project**.

doc/topics/git/useful_git_commands.md

@@ -74,7 +74,7 @@ message.
 git stash save
 ```
 
-The default behavor of `stash` is to save, so you can also use just:
+The default behavior of `stash` is to save, so you can also use just:
 
 ```sh
 git stash

doc/user/admin_area/settings/account_and_limit_settings.md

@@ -106,7 +106,7 @@ To set a limit on how long personal access tokens are valid:
 
 1. Navigate to **Admin Area > Settings > General**.
 1. Expand the **Account and limit** section.
-1. Fill in the **Maximun allowable lifetime for personal access tokens (days)** field.
+1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field.
 1. Click **Save changes**.
 
 Once a lifetime for personal access tokens is set, GitLab will:

doc/user/admin_area/settings/external_authorization.md

@@ -62,7 +62,7 @@ The available required properties are:
   requesting authorization if no specific label is defined on the project
 
 When using TLS Authentication with a self signed certificate, the CA certificate
-needs to be trused by the openssl installation. When using GitLab installed using
+needs to be trusted by the openssl installation. When using GitLab installed using
 Omnibus, learn to install a custom CA in the
 [omnibus documentation][omnibus-ssl-docs]. Alternatively learn where to install
 custom certificates using `openssl version -d`.

doc/user/clusters/crossplane.md

@@ -222,7 +222,7 @@ The Auto DevOps pipeline can be run with the following options:
 
 The Environment variables, `AUTO_DEVOPS_POSTGRES_MANAGED` and `AUTO_DEVOPS_POSTGRES_MANAGED_CLASS_SELECTOR` need to be set to provision PostgreSQL using Crossplane
 
-Alertnatively, the following options can be overridden from the values for the Helm chart.
+Alternatively, the following options can be overridden from the values for the Helm chart.
 
 - `postgres.managed` set to true which will select a default resource class.
      The resource class needs to be marked with the annotation
@@ -235,7 +235,7 @@ Alertnatively, the following options can be overridden from the values for the H
      will select the CloudSQLInstance class `cloudsqlinstancepostgresql-standard`
      to satisfy the claim request.
 
-The Auto DevOps pipeline should provision a PostgresqlInstance when it runs succesfully.
+The Auto DevOps pipeline should provision a PostgresqlInstance when it runs successfully.
 
 Verify creation of the PostgreSQL Instance.
 

doc/user/markdown.md

@@ -275,7 +275,7 @@ In GitLab, front matter is only used in Markdown files and wiki pages, not the o
 places where Markdown formatting is supported. It must be at the very top of the document,
 and must be between delimiters, as explained below.
 
-The following delimeters are supported:
+The following delimiters are supported:
 
 - YAML (`---`):
 
@@ -601,7 +601,7 @@ Inline `code` has `back-ticks around` it.
 ---
 
 Similarly, a whole block of code can be fenced with triple backticks ```` ``` ````,
-triple tildes (`~~~`), or indended 4 or more spaces to achieve a similar effect for
+triple tildes (`~~~`), or indented 4 or more spaces to achieve a similar effect for
 a larger body of code.
 
 ~~~

doc/user/packages/index.md

@@ -18,7 +18,7 @@ The Packages feature allows GitLab to act as a repository for the following:
 TIP: **Tip:**
 Don't you see your package management system supported yet? Consider contributing
 to GitLab. This [development documentation](../../development/packages.md) will
-guide you through the process. Or check out how other members of the commmunity
+guide you through the process. Or check out how other members of the community
 are adding support for [PHP](https://gitlab.com/gitlab-org/gitlab/merge_requests/17417) or [Terraform](https://gitlab.com/gitlab-org/gitlab/merge_requests/18834).
 
 NOTE: **Note** We are especially interested in adding support for [PyPi](https://gitlab.com/gitlab-org/gitlab/issues/10483), [RubyGems](https://gitlab.com/gitlab-org/gitlab/issues/803), [Debian](https://gitlab.com/gitlab-org/gitlab/issues/5835), and [RPM](https://gitlab.com/gitlab-org/gitlab/issues/5932).

doc/user/project/import/perforce.md

@@ -19,7 +19,7 @@ Git:
    said 'You need to stop work on that new feature and fix this security
    vulnerability' you can do so very easily in Git.
 1. Having a complete copy of the project and its history on your local machine
-   means every transaction is superfast and Git provides that. You can branch/merge
+   means every transaction is very fast and Git provides that. You can branch/merge
    and experiment in isolation, then clean up your mess before sharing your new
    cool stuff with everyone.
 1. Git also made code review simple because you could share your changes without

doc/user/project/integrations/generic_alerts.md

@@ -30,7 +30,7 @@ You can customize the payload by sending the following parameters. All fields ar
 | `start_time` | DateTime | The time of the incident. If none is provided, a timestamp of the issue will be used. |
 | `service` | String | The affected service. |
 | `monitoring_tool` | String |  The name of the associated monitoring tool. |
-| `hosts` | String or Array | One or more hosts, as to where this incident ocurred. |
+| `hosts` | String or Array | One or more hosts, as to where this incident occurred. |
 
 Example request:
 

doc/user/project/issues/managing_issues.md

@@ -66,7 +66,7 @@ configured.
 
 When you click this link, an email address is generated and displayed, which should be used
 by **you only**, to create issues in this project. You can save this address as a
-contact in your email client for easy acceess.
+contact in your email client for easy access.
 
 CAUTION: **Caution:**
 This is a private email address, generated just for you. **Keep it to yourself**,
@@ -207,7 +207,7 @@ and https://gitlab.example.com/group/otherproject/issues/23.
 ```
 
 will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to,
-as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as it does
+as well as `#22` and `#23` in `group/otherproject`. `#17` won't be closed as it does
 not match the pattern. It works with multi-line commit messages as well as one-liners
 when used from the command line with `git commit -m`.
 

doc/user/project/merge_requests/creating_merge_requests.md

@@ -172,7 +172,7 @@ this feature. If it's not enabled to your instance, you may ask your GitLab
 administrator to do so.
 
 This is a private email address, generated just for you. **Keep it to yourself**
-as anyone who gets ahold of it can create issues or merge requests as if they were you.
+as anyone who has it can create issues or merge requests as if they were you.
 You can add this address to your contact list for easy access.
 
 ![Create new merge requests by email](img/create_from_email.png)

doc/user/project/merge_requests/getting_started.md

@@ -51,7 +51,7 @@ options to include straightaway (you can also add them later by
 clicking the **Edit** button on the merge request's page at the
 top-right side):
 
-- [Assign](#assignee) the merge request to a colleage for review.With GitLab Starter and higher tiers, you can [assign it to more than one person at a time](#multiple-assignees-starter).
+- [Assign](#assignee) the merge request to a colleague for review.With GitLab Starter and higher tiers, you can [assign it to more than one person at a time](#multiple-assignees-starter).
 - Set a [milestone](../milestones/index.md) to track time-sensitive changes.
 - Add [labels](../labels.md) to help contextualize and filter your merge requests over time.
 - Require [approval](merge_request_approvals.md) from your team. **(STARTER)**

doc/user/project/milestones/index.md

@@ -20,7 +20,7 @@ Milestones can be used as Agile sprints so that you can track all issues and mer
 
 ## Milestones as releases
 
-Similarily, milestones can be used as releases. To do so:
+Similarly, milestones can be used as releases. To do so:
 
 1. Set the milestone due date to represent the release date of your release and leave the milestone start date blank.
 1. Set the milestone title to the version of your release, such as `Version 9.4`.

doc/user/project/pages/custom_domains_ssl_tls_certification/index.md

@@ -134,7 +134,7 @@ If you're using CloudFlare, check
   `domain.com` to your GitLab Pages site. Use an `A` record instead.
 > - **Do not** add any special chars after the default Pages
   domain. E.g., don't point `subdomain.domain.com` to
-  or `namespace.gitlab.io/`. Some domain hosting providers may request a trailling dot (`namespace.gitlab.io.`), though.
+  or `namespace.gitlab.io/`. Some domain hosting providers may request a trailing dot (`namespace.gitlab.io.`), though.
 > - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/blog/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017.
 > - GitLab Pages IP on GitLab.com [has changed](https://about.gitlab.com/blog/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains)
   from `52.167.214.135` to `35.185.44.232` in 2018.

doc/user/project/pages/getting_started/new_or_existing_website.md

@@ -17,7 +17,7 @@ To do so, follow the steps below.
    [Pages domain names](../getting_started_part_one.md#gitlab-pages-default-domain-names).
 1. Clone it to your local computer, add your website
    files to your project, add, commit and push to GitLab.
-   Alternativelly, you can run `git init` in your local directory,
+   Alternatively, you can run `git init` in your local directory,
    add the remote URL:
    `git remote add origin git@gitlab.com:namespace/project-name.git`,
    then add, commit, and push to GitLab.

doc/user/project/repository/file_finder.md

@@ -37,7 +37,7 @@ the `app/controllers/admin/deploy_keys_controller.rb` file.
 
 Using fuzzy search, we start by typing letters that get us closer to the file.
 
-**Protip:** To narrow down your search, include `/` in your search terms.
+**Tip:** To narrow down your search, include `/` in your search terms.
 
 ![Find file button](img/file_finder_find_file.png)
 

lib/gitlab/graphql/docs/renderer.rb

@@ -10,7 +10,7 @@ module Gitlab
       # It uses graphql-docs helpers and schema parser, more information in https://github.com/gjtorikian/graphql-docs.
       #
       # Arguments:
-      #   schema - the GraphQL schema defition. For GitLab should be: GitlabSchema.graphql_definition
+      #   schema - the GraphQL schema definition. For GitLab should be: GitlabSchema.graphql_definition
       #   output_dir: The folder where the markdown files will be saved
       #   template: The path of the haml template to be parsed
       class Renderer

lib/gitlab/graphql/docs/templates/default.md.haml

@@ -9,11 +9,15 @@
 
   The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql).
 
-  ## Objects
+Each table below documents a GraphQL type. Types match loosely to models, but not all
+fields and methods on a model are available via GraphQL.
 \
 - objects.each do |type|
   - unless type[:fields].empty?
-    = "### #{type[:name]}"
+    = "## #{type[:name]}"
+    - if type[:description]&.present?
+      \
+      = type[:description]
     \
     ~ "| Name  | Type  | Description |"
     ~ "| ---   |  ---- | ----------  |"