diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-12-06 03:08:37 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-12-06 03:08:37 +0000 |
| commit | 43c0fa568b3e3689abd3d57eb058433f33c9df1c (patch) | |
| tree | e3161c4e6c1f327bbb42e36ef5705978833702ad /doc/development | |
| parent | 92106208758b8901436ec62ce19390b1ee652045 (diff) | |
| download | gitlab-ce-43c0fa568b3e3689abd3d57eb058433f33c9df1c.tar.gz | |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development')
60 files changed, 115 insertions, 112 deletions
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 75020e25b57..925f948e118 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -170,7 +170,7 @@ See also: - [Exposing Global IDs](#exposing-global-ids). - [Mutation arguments](#object-identifier-arguments). -- [Deprecating Global IDs](#deprecate-global-ids). +- [Deprecating Global IDs](#deprecate-global-ids). We have a custom scalar type (`Types::GlobalIDType`) which should be used as the type of input and output arguments when the value is a `GlobalID`. The benefits @@ -2263,7 +2263,7 @@ end 1. 95% of the resolver specs use arguments that are Ruby objects, as opposed to when using the GraphQL API only strings and integers are used. This works fine in most cases. - 1. If your resolver takes arguments that use a `prepare` proc, such as a resolver that accepts timeframe + 1. If your resolver takes arguments that use a `prepare` proc, such as a resolver that accepts time frame arguments (`TimeFrameArguments`), you must pass the `arg_style: :internal_prepared` parameter into the `resolve` method. This tells the code to convert the arguments into strings and integers and pass them through regular argument handling, ensuring that the `prepare` proc is called correctly. diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index 3e911bb082b..312bf2b1bb7 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_rules.md @@ -221,7 +221,7 @@ It is responsible for parsing `approval_rules_attributes` parameter to: - Filter the group IDs whether they are visible to user. - Identify the `any_approver` rule. - Append hidden groups to it when specified. -- Append user defined inapplicable (rules that does not apply to MR's target +- Append user defined inapplicable (rules that do not apply to the merge request's target branch) approval rules. ## Flow diff --git a/doc/development/architecture.md b/doc/development/architecture.md index a641bf7d208..5eb1dcc3208 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -624,7 +624,7 @@ Mattermost is an open source, private cloud, Slack-alternative from <https://mat - Layer: Core Service (Data) - GitLab.com: [Storage Architecture](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/#storage-architecture) -MinIO is an object storage server released under the GNU AGPL v3.0. It is compatible with Amazon S3 cloud storage service. It is best suited for storing unstructured data such as photos, videos, log files, backups, and container / VM images. Size of an object can range from a few KBs to a maximum of 5TB. +MinIO is an object storage server released under the GNU AGPL v3.0. It is compatible with Amazon S3 cloud storage service. It is best suited for storing unstructured data such as photos, videos, log files, backups, and container / VM images. Size of an object can range from a few KB to a maximum of 5 TB. #### NGINX diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md index 1a0f0ec5b5f..1919807b81f 100644 --- a/doc/development/cascading_settings.md +++ b/doc/development/cascading_settings.md @@ -153,7 +153,7 @@ Renders the label for a checkbox setting. [`_setting_label_fieldset.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/c2736823b8e922e26fd35df4f0cd77019243c858/app/views/shared/namespaces/cascading_settings/_setting_label_fieldset.html.haml) -Renders the label for a fieldset setting. +Renders the label for a `fieldset` setting. | Local | Description | Type | Required (default value) | |:-----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------|:-------------------------| diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 209e971c952..93ff10a4132 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -155,7 +155,7 @@ with [domain expertise](#domain-experts). | `~frontend` changes (*1*) | [Frontend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_frontend). | | `~UX` user-facing changes (*3*) | [Product Designer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_reviewers_UX). Refer to the [design and user interface guidelines](contributing/design.md) for details. | | Adding a new JavaScript library (*1*) | - [Frontend foundations member](https://about.gitlab.com/direction/manage/foundations/) if the library significantly increases the [bundle size](https://gitlab.com/gitlab-org/frontend/playground/webpack-memory-metrics/-/blob/master/doc/report.md).<br/>- A [legal department member](https://about.gitlab.com/handbook/legal/) if the license used by the new library hasn't been approved for use in GitLab.<br/><br/>More information about license compatibility can be found in our [GitLab Licensing and Compatibility documentation](licensing.md). | -| A new dependency or a file system change | - [Distribution team member](https://about.gitlab.com/company/team/). See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/systems/distribution/#how-to-work-with-distribution) for more details.<br/>- For Rubygems, request an [AppSec review](gemfile.md#request-an-appsec-review). | +| A new dependency or a file system change | - [Distribution team member](https://about.gitlab.com/company/team/). See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/systems/distribution/#how-to-work-with-distribution) for more details.<br/>- For RubyGems, request an [AppSec review](gemfile.md#request-an-appsec-review). | | `~documentation` or `~UI text` changes | [Technical writer](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) based on assignments in the appropriate [DevOps stage group](https://about.gitlab.com/handbook/product/categories/#devops-stages). | | Changes to development guidelines | Follow the [review process](development_processes.md#development-guidelines-review) and get the approvals accordingly. | | End-to-end **and** non-end-to-end changes (*4*) | [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors). | diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index 52503f2d9c8..b568809ea4e 100644 --- a/doc/development/dangerbot.md +++ b/doc/development/dangerbot.md @@ -132,7 +132,7 @@ have had the chance to add to `helper.labels_to_add`. #### Shared rules and plugins If the rule or plugin you implement can be useful for other projects, think about -upstreaming them to the [`gitlab-dangerfiles`](https://gitlab.com/gitlab-org/ruby/gems/gitlab-dangerfiles) project. +adding them upstream to the [`gitlab-dangerfiles`](https://gitlab.com/gitlab-org/ruby/gems/gitlab-dangerfiles) project. #### Enable Danger on a project diff --git a/doc/development/database/adding_database_indexes.md b/doc/development/database/adding_database_indexes.md index 053747bac8c..f784d161ced 100644 --- a/doc/development/database/adding_database_indexes.md +++ b/doc/development/database/adding_database_indexes.md @@ -354,7 +354,7 @@ Use the asynchronous index helpers on your local environment to test changes for For very large tables, index destruction can be a challenge to manage. While `remove_concurrent_index` removes indexes in a way that does not block normal traffic, it can still be problematic if index destruction runs for -during autovacuum. Necessary database operations like `autovacuum` cannot run, and +during `autovacuum`. Necessary database operations like `autovacuum` cannot run, and the deployment process on GitLab.com is blocked while waiting for index destruction to finish. diff --git a/doc/development/database/avoiding_downtime_in_migrations.md b/doc/development/database/avoiding_downtime_in_migrations.md index 0b4897507de..5b6886b8a41 100644 --- a/doc/development/database/avoiding_downtime_in_migrations.md +++ b/doc/development/database/avoiding_downtime_in_migrations.md @@ -483,7 +483,7 @@ for batched background migration: To monitor the health of the database, use these additional metrics: -- [PostgreSQL Tuple Statistics](https://dashboards.gitlab.net/d/000000167/postgresql-tuple-statistics?orgId=1&refresh=1m): if you see high rate of updates for the tables being actively converted, or increasing percentage of dead tuples for this table, it might mean that autovacuum cannot keep up. +- [PostgreSQL Tuple Statistics](https://dashboards.gitlab.net/d/000000167/postgresql-tuple-statistics?orgId=1&refresh=1m): if you see high rate of updates for the tables being actively converted, or increasing percentage of dead tuples for this table, it might mean that `autovacuum` cannot keep up. - [PostgreSQL Overview](https://dashboards.gitlab.net/d/000000144/postgresql-overview?orgId=1): if you see high system usage or transactions per second (TPS) on the primary database server, it might mean that the migration is causing problems. ### Prometheus metrics @@ -504,8 +504,8 @@ If the migration has not completed, the subsequent steps fail anyway. By checkin aim to have more helpful error message. 1. Create indexes using the `bigint` columns that match the existing indexes using the `integer` column ([see an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb#L28-34)). -1. Create foreign keys (FK) using the `bigint` columns that match the existing FKs using the -`integer` column. Do this both for FK referencing other tables, and FKs that reference the table +1. Create foreign keys (FK) using the `bigint` columns that match the existing FK using the +`integer` column. Do this both for FK referencing other tables, and FK that reference the table that is being migrated ([see an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb#L36-43)). 1. Inside a transaction, swap the columns: 1. Lock the tables involved. To reduce the chance of hitting a deadlock, we recommended to do this in parent to child order ([see an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb#L47)). @@ -514,7 +514,7 @@ that is being migrated ([see an example](https://gitlab.com/gitlab-org/gitlab/-/ 1. Swap the defaults ([see an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb#L59-62)). 1. Swap the PK constraint (if any) ([see an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb#L64-68)). 1. Remove old indexes and rename new ones ([see an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb#L70-72)). - 1. Remove old FKs (if still present) and rename new ones ([see an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb#L74)). + 1. Remove old foreign keys (if still present) and rename new ones ([see an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb#L74)). See example [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66088), and [migration](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb). diff --git a/doc/development/database/background_migrations.md b/doc/development/database/background_migrations.md index fe62bbc6b14..d805686e84d 100644 --- a/doc/development/database/background_migrations.md +++ b/doc/development/database/background_migrations.md @@ -412,7 +412,7 @@ When looking at the batch execution time versus the delay time, the execution ti should fit comfortably within the delay time for a few reasons: - To allow for a variance in query times. -- To allow autovacuum to catch up after periods of high churn. +- To allow `autovacuum` to catch up after periods of high churn. Never try to optimize by fully filling the delay window even if you are confident the queries themselves have no timing variance. diff --git a/doc/development/database/database_debugging.md b/doc/development/database/database_debugging.md index 31355ef9707..edc35dd95e8 100644 --- a/doc/development/database/database_debugging.md +++ b/doc/development/database/database_debugging.md @@ -107,7 +107,7 @@ The new connection should be working now. Use these instructions for exploring the GitLab database while developing with the GDK: 1. Install or open [Visual Studio Code](https://code.visualstudio.com/download). -1. Install the [PostgreSQL VSCode Extension](https://marketplace.visualstudio.com/items?itemName=ckolkman.vscode-postgres). +1. Install the [PostgreSQL VS Code Extension](https://marketplace.visualstudio.com/items?itemName=ckolkman.vscode-postgres). 1. In Visual Studio Code select **PostgreSQL Explorer** in the left toolbar. 1. In the top bar of the new window, select `+` to **Add Database Connection**, and follow the prompts to fill in the details: 1. **Hostname**: the path to the PostgreSQL folder in your GDK directory (for example `/dev/gitlab-development-kit/postgresql`). diff --git a/doc/development/database/efficient_in_operator_queries.md b/doc/development/database/efficient_in_operator_queries.md index 0f65dcfef9e..8badc4fb9d3 100644 --- a/doc/development/database/efficient_in_operator_queries.md +++ b/doc/development/database/efficient_in_operator_queries.md @@ -126,8 +126,7 @@ For very large groups the database queries can easily time out, causing HTTP 500 ## Optimizing ordered `IN` queries -In the talk -["How to teach an elephant to dance rock'n'roll"](https://www.youtube.com/watch?v=Ha38lcjVyhQ), +In the talk ["How to teach an elephant to dance rock'n'roll"](https://www.youtube.com/watch?v=Ha38lcjVyhQ), Maxim Boguk demonstrated a technique to optimize a special class of ordered `IN` queries, such as our ordered group-level queries. @@ -918,11 +917,11 @@ the `LIMIT` is reached or no more data can be found. Here's an outline of the steps we take in the recursive CTE query (expressing the steps in SQL is non-trivial but is explained next): -1. Sort the initial resultset according to the `ORDER BY` clause. +1. Sort the initial `resultset` according to the `ORDER BY` clause. 1. Pick the top cursor to fetch the record, this is our first record. In the example, this cursor would be (`2020-01-05`, `3`) for `project_id=9`. 1. We can use (`2020-01-05`, `3`) to fetch the next issue respecting the `ORDER BY` clause -`project_id=9` filter. This produces an updated resultset. +`project_id=9` filter. This produces an updated `resultset`. | `project_ids` | `created_at_values` | `id_values` | | ------------- | ------------------- | ----------- | @@ -931,7 +930,7 @@ this cursor would be (`2020-01-05`, `3`) for `project_id=9`. | 10 | 2020-01-15 | 7 | | **9** | **2020-01-06** | **6** | -1. Repeat 1 to 3 with the updated resultset until we have fetched `N=20` records. +1. Repeat 1 to 3 with the updated `resultset` until we have fetched `N=20` records. ### Initializing the recursive CTE query diff --git a/doc/development/database/keyset_pagination.md b/doc/development/database/keyset_pagination.md index 21bce41012e..42d7458b45a 100644 --- a/doc/development/database/keyset_pagination.md +++ b/doc/development/database/keyset_pagination.md @@ -159,7 +159,7 @@ configuration is necessary: - Function-based ordering. - Ordering with a custom tie-breaker column, like `iid`. -These order objects can be defined in the model classes as normal ActiveRecord scopes, there is no special behavior that prevents using these scopes elsewhere (kaminari, background jobs). +These order objects can be defined in the model classes as normal ActiveRecord scopes, there is no special behavior that prevents using these scopes elsewhere (Kaminari, background jobs). ### `NULLS LAST` ordering diff --git a/doc/development/database/loose_foreign_keys.md b/doc/development/database/loose_foreign_keys.md index 962cd2602bc..a618a1ffdee 100644 --- a/doc/development/database/loose_foreign_keys.md +++ b/doc/development/database/loose_foreign_keys.md @@ -134,7 +134,7 @@ scripts/decomposition/generate-loose-foreign-key -c ci_job_token_project_scope_l ``` To swap all the foreign keys (all having `_id` appended), but not create a new branch (only commit -the changes) and not create rspecs, run: +the changes) and not create RSpec tests, run: ```shell scripts/decomposition/generate-loose-foreign-key -c --no-branch --no-rspec _id diff --git a/doc/development/database/pagination_performance_guidelines.md b/doc/development/database/pagination_performance_guidelines.md index 0f98b50d95c..b06839979da 100644 --- a/doc/development/database/pagination_performance_guidelines.md +++ b/doc/development/database/pagination_performance_guidelines.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Pagination performance guidelines -The following document gives a few ideas for improving the pagination (sorting) performance. These apply both on [offset](pagination_guidelines.md#offset-pagination) and [keyset](pagination_guidelines.md#keyset-pagination) paginations. +The following document gives a few ideas for improving the pagination (sorting) performance. These apply both on [offset](pagination_guidelines.md#offset-pagination) and [keyset](pagination_guidelines.md#keyset-pagination) pagination. ## Tie-breaker column diff --git a/doc/development/database/polymorphic_associations.md b/doc/development/database/polymorphic_associations.md index f3c9bf1276f..bb7eb46b448 100644 --- a/doc/development/database/polymorphic_associations.md +++ b/doc/development/database/polymorphic_associations.md @@ -98,10 +98,10 @@ AND source_id = 4 Instead such a table should be broken up into separate tables. For example, you may end up with 4 tables in this case: -- project_members -- group_members -- pending_project_members -- pending_group_members +- `project_members` +- `group_members` +- `pending_project_members` +- `pending_group_members` This makes querying data trivial. For example, to get the members of a group you'd run: diff --git a/doc/development/database/understanding_explain_plans.md b/doc/development/database/understanding_explain_plans.md index fff9d755e9a..094bd6b346f 100644 --- a/doc/development/database/understanding_explain_plans.md +++ b/doc/development/database/understanding_explain_plans.md @@ -826,4 +826,4 @@ A more extensive guide on understanding query plans can be found in the [presentation](https://public.dalibo.com/exports/conferences/_archives/_2012/201211_explain/understanding_explain.pdf) from [Dalibo.org](https://www.dalibo.com/en/). -Depesz's blog also has a good [section](https://www.depesz.com/tag/unexplainable/) dedicated to query plans. +The Depesz blog also has a good [section](https://www.depesz.com/tag/unexplainable/) dedicated to query plans. diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 7fbc48af91c..e66be062986 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -150,7 +150,7 @@ Include in the MR description: - Write the raw SQL in the MR description. Preferably formatted nicely with [pgFormatter](https://sqlformat.darold.net) or - [paste.depesz.com](https://paste.depesz.com) and using regular quotes + <https://paste.depesz.com> and using regular quotes <!-- vale gitlab.NonStandardQuotes = NO --> (for example, `"projects"."id"`) and avoiding smart quotes (for example, `“projects”.“id”`). <!-- vale gitlab.NonStandardQuotes = YES --> diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index f51197575b2..cd87704dda3 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -158,7 +158,7 @@ also aid in consistency, which is important for localization. All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). The [documentation website](https://docs.gitlab.com) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown), -a "flavored" Kramdown engine to render pages from Markdown to HTML. The use of Kramdown's +a "flavored" Kramdown engine to render pages from Markdown to HTML. The use of Kramdown features is limited by our linters, so, use regular Markdown and follow the rules in the linked style guide. You can't use Kramdown-specific markup (for example, `{:.class}`). @@ -396,8 +396,12 @@ when published. Example: ### Emphasis +<!-- vale gitlab.Spelling = NO --> + Use **bold** rather than italic to provide emphasis. GitLab uses a sans-serif font and italic text does not stand out as much as it would in a serif font. For details, see [Butterick's Practical Typography guide on bold or italic](https://practicaltypography.com/bold-or-italic.html). +<!-- vale gitlab.Spelling = YES --> + You can use italics when you are introducing a term for the first time. Otherwise, use bold. - Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 8ddc4c21af9..cef42c56bb0 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -113,9 +113,9 @@ Uses a [Pattern Capture token filter](https://www.elastic.co/guide/en/elasticsea Patterns: -- `"(\\p{Ll}+|\\p{Lu}\\p{Ll}+|\\p{Lu}+)"`: captures CamelCased and lowedCameCased strings as separate tokens +- `"(\\p{Ll}+|\\p{Lu}\\p{Ll}+|\\p{Lu}+)"`: captures CamelCase and lowerCamelCase strings as separate tokens - `"(\\d+)"`: extracts digits -- `"(?=([\\p{Lu}]+[\\p{L}]+))"`: captures CamelCased strings recursively. For example: `ThisIsATest` => `[ThisIsATest, IsATest, ATest, Test]` +- `"(?=([\\p{Lu}]+[\\p{L}]+))"`: captures CamelCase strings recursively. For example: `ThisIsATest` => `[ThisIsATest, IsATest, ATest, Test]` - `'"((?:\\"|[^"]|\\")*)"'`: captures terms inside quotes, removing the quotes - `"'((?:\\'|[^']|\\')*)'"`: same as above, for single-quotes - `'\.([^.]+)(?=\.|\s|\Z)'`: separate terms with periods in-between diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index 67166a93cb4..af45603782f 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.md @@ -109,15 +109,15 @@ Text input examples: </gl-form-group> ``` -Textarea examples: +`textarea` examples: ```html -<!-- Textarea with label --> +<!-- textarea with label --> <gl-form-group :label="__('Issue description')" label-for="issue-description"> <gl-form-textarea id="issue-description" v-model="description" /> </gl-form-group> -<!-- Textarea with hidden label --> +<!-- textarea with hidden label --> <gl-form-group :label="__('Issue description')" label-for="issue-description" label-sr-only> <gl-form-textarea id="issue-description" v-model="description" /> </gl-form-group> @@ -347,7 +347,7 @@ Keep in mind that: See the [Pajamas Keyboard-only page](https://design.gitlab.com/accessibility-audits/keyboard-only/) for more detail. -## Tabindex +## `tabindex` Prefer **no** `tabindex` to using `tabindex`, since: diff --git a/doc/development/fe_guide/content_editor.md b/doc/development/fe_guide/content_editor.md index 8cc274c732e..982033cf2ad 100644 --- a/doc/development/fe_guide/content_editor.md +++ b/doc/development/fe_guide/content_editor.md @@ -11,7 +11,7 @@ experience for [GitLab Flavored Markdown](../../user/markdown.md) in the GitLab It also serves as the foundation for implementing Markdown-focused editors that target other engines, like static site generators. -We use [tiptap 2.0](https://tiptap.dev/) and [ProseMirror](https://prosemirror.net/) +We use [Tiptap 2.0](https://tiptap.dev/) and [ProseMirror](https://prosemirror.net/) to build the Content Editor. These frameworks provide a level of abstraction on top of the native [`contenteditable`](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content) web technology. @@ -209,7 +209,7 @@ the following events: - `blur` - `error`. -Learn more about these events in [Tiptap's event guide](https://tiptap.dev/api/events/). +Learn more about these events in [the Tiptap event guide](https://tiptap.dev/api/events/). ```html <script> @@ -255,13 +255,13 @@ provides all the necessary extensions to support #### Implement new extensions Extensions are the building blocks of the Content Editor. You can learn how to implement -new ones by reading [Tiptap's guide](https://tiptap.dev/guide/custom-extensions). +new ones by reading [the Tiptap guide](https://tiptap.dev/guide/custom-extensions). We recommend checking the list of built-in [nodes](https://tiptap.dev/api/nodes) and [marks](https://tiptap.dev/api/marks) before implementing a new extension from scratch. Store the Content Editor extensions in the `~/content_editor/extensions` directory. -When using a Tiptap's built-in extension, wrap it in a ES6 module inside this directory: +When using a Tiptap built-in extension, wrap it in a ES6 module inside this directory: ```javascript export { Bold as default } from '@tiptap/extension-bold'; @@ -326,10 +326,10 @@ sequenceDiagram A->>E: setContent(document) ``` -Deserializers live in the extension modules. Read Tiptap's -[parseHTML](https://tiptap.dev/guide/custom-extensions#parse-html) and -[addAttributes](https://tiptap.dev/guide/custom-extensions#attributes) documentation to -learn how to implement them. Titap's API is a wrapper around ProseMirror's +Deserializers live in the extension modules. Read Tiptap documentation about +[`parseHTML`](https://tiptap.dev/guide/custom-extensions#parse-html) and +[`addAttributes`](https://tiptap.dev/guide/custom-extensions#attributes) to +learn how to implement them. The Tiptap API is a wrapper around ProseMirror's [schema spec API](https://prosemirror.net/docs/ref/#model.SchemaSpec). #### Serialization diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index fc91ff55b24..232689080ea 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -45,7 +45,7 @@ Use your best judgment when to use it and contribute new points through merge re - [ ] Check off tasks on your created task list to keep everyone updated on the progress - [ ] [Share your work early with reviewers/maintainers](#share-your-work-early) -- [ ] Share your work with UXer and Product Manager with Screenshots and/or [GIF's](https://about.gitlab.com/handbook/product/making-gifs/). They are easy to create for you and keep them up to date. +- [ ] Share your work with UXer and Product Manager with Screenshots and/or [GIF images](https://about.gitlab.com/handbook/product/making-gifs/). They are easy to create for you and keep them up to date. - [ ] If you are blocked on something let everyone on the issue know through a comment. - [ ] Are you unable to work on this issue for a longer period of time, also let everyone know. - [ ] **Documentation** Update/add docs for the new feature, see `docs/`. Ping one of the documentation experts/reviewers @@ -58,7 +58,7 @@ Use your best judgment when to use it and contribute new points through merge re - [ ] Did you check the mobile view? - [ ] Check the built webpack bundle (For the report run `WEBPACK_REPORT=true gdk start`, then open `webpack-report/index.html`) if we have unnecessary bloat due to wrong references, including libraries multiple times, etc.. If you need help contact the webpack [domain expert](https://about.gitlab.com/handbook/engineering/frontend/#frontend-domain-experts) - [ ] **Tests** Not only greenfield tests - Test also all bad cases that come to your mind. -- [ ] If you have multiple MR's then also smoke test against the final merge. +- [ ] If you have multiple MRs then also smoke test against the final merge. - [ ] Are there any big changes on how and especially how frequently we use the API then let production know about it - [ ] Smoke test of the RC on dev., staging., canary deployments and .com - [ ] Follow up on issues that came out of the review. Create issues for discovered edge cases that should be covered in future iterations. diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 4c0259638d0..0fec38b1200 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -109,7 +109,7 @@ Default client accepts two parameters: `resolvers` and `config`. If you are making multiple queries to the same Apollo client object you might encounter the following error: `Cache data may be lost when replacing the someProperty field of a Query object. To address this problem, either ensure all objects of SomeEntityhave an id or a custom merge function`. We are already checking `ID` presence for every GraphQL type that has an `ID`, so this shouldn't be the case. Most likely, the `SomeEntity` type doesn't have an `ID` property, and to fix this warning we need to define a custom merge function. -We have some client-wide types with `merge: true` defined in the default client as [typePolicies](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/lib/graphql.js) (this means that Apollo will merge existing and incoming responses in the case of subsequent queries). Consider adding `SomeEntity` there or defining a custom merge function for it. +We have some client-wide types with `merge: true` defined in the default client as [`typePolicies`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/lib/graphql.js) (this means that Apollo will merge existing and incoming responses in the case of subsequent queries). Consider adding `SomeEntity` there or defining a custom merge function for it. ## GraphQL Queries diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md index 38fb926197b..0536d1c5c77 100644 --- a/doc/development/fe_guide/style/javascript.md +++ b/doc/development/fe_guide/style/javascript.md @@ -7,7 +7,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/development/fe_guide/style_guide_ # JavaScript style guide -We use [Airbnb's JavaScript Style Guide](https://github.com/airbnb/javascript) and its accompanying +We use [the Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) and its accompanying linter to manage most of our JavaScript style guidelines. In addition to the style guidelines set by Airbnb, we also have a few specific rules @@ -16,11 +16,11 @@ listed below. NOTE: You can run ESLint locally by running `yarn run lint:eslint:all` or `yarn run lint:eslint $PATH_TO_FILE`. -## Avoid forEach +## Avoid `forEach` -Avoid forEach when mutating data. Use `map`, `reduce` or `filter` instead of `forEach` +Avoid `forEach` when mutating data. Use `map`, `reduce` or `filter` instead of `forEach` when mutating data. This minimizes mutations in functions, -which aligns with [Airbnb's style guide](https://github.com/airbnb/javascript#testing--for-real). +which aligns with [the Airbnb style guide](https://github.com/airbnb/javascript#testing--for-real). ```javascript // bad diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md index c20ade6bc1d..7a5c955db93 100644 --- a/doc/development/fe_guide/style/scss.md +++ b/doc/development/fe_guide/style/scss.md @@ -43,7 +43,7 @@ result (such as `ml-1` becoming `gl-ml-2`). #### Where should you put new utility classes? -If a class you need has not been added to GitLab UI, you get to add it! Follow the naming patterns documented in the [utility files](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/main/src/scss/utility-mixins) and refer to [GitLab UI's CSS documentation](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/adding_css.md#adding-utility-mixins) for more details, especially about adding responsive and stateful rules. +If a class you need has not been added to GitLab UI, you get to add it! Follow the naming patterns documented in the [utility files](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/main/src/scss/utility-mixins) and refer to the [GitLab UI CSS documentation](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/adding_css.md#adding-utility-mixins) for more details, especially about adding responsive and stateful rules. If it is not possible to wait for a GitLab UI update (generally one day), add the class to [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/stylesheets/utilities.scss) following the same naming conventions documented in GitLab UI. A follow-up issue to backport the class to GitLab UI and delete it from GitLab should be opened. diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index c9efb8e939d..762ef852d74 100644 --- a/doc/development/fe_guide/tooling.md +++ b/doc/development/fe_guide/tooling.md @@ -212,7 +212,7 @@ yarn run lint:prettier:fix Formats all files in the repository with Prettier. -### VSCode Settings +### VS Code Settings #### Select Prettier as default formatter diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 19bbfa314ea..362998c16af 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -431,7 +431,7 @@ export default { Refer to [Vuex documentation](https://vuex.vuejs.org/guide/testing.html) regarding testing Actions, Getters and Mutations. -#### Testing components that need a store +#### Testing components that need a store Smaller components might use `store` properties to access the data. To write unit tests for those components, we need to include the store and provide the correct state: diff --git a/doc/development/fe_guide/widgets.md b/doc/development/fe_guide/widgets.md index 3364c778d76..edb8559da48 100644 --- a/doc/development/fe_guide/widgets.md +++ b/doc/development/fe_guide/widgets.md @@ -44,7 +44,7 @@ All editable sidebar widgets should use [`SidebarEditableItem`](https://gitlab.c We aim to make widgets as reusable as possible. That's why we should avoid adding any external state bindings to widgets or to their child components. This includes Vuex mappings and mediator stores. -## Widget's responsibility +## Widget responsibility A widget is responsible for fetching and updating an entity it's designed for (assignees, iterations, and so on). This means a widget should **always** fetch data (if it's not in Apollo cache already). @@ -78,7 +78,7 @@ To handle the same logic for query updates, we **alias** query fields. For examp - `group` or `project` become `workspace` - `issue`, `epic`, or `mergeRequest` become `issuable` -Unfortunately, Apollo assigns aliased fields a typename of `undefined`, so we need to fetch `__typename` explicitly: +Unfortunately, Apollo assigns aliased fields a `typename` of `undefined`, so we need to fetch `__typename` explicitly: ```plaintext query issueConfidential($fullPath: ID!, $iid: String) { diff --git a/doc/development/feature_development.md b/doc/development/feature_development.md index 645505b2da1..b9e093b9479 100644 --- a/doc/development/feature_development.md +++ b/doc/development/feature_development.md @@ -127,7 +127,7 @@ See [database guidelines](database/index.md). - [Security Scanners](integrations/secure.md) - [Secure Partner Integration](integrations/secure_partner_integration.md) - [How to run Jenkins in development environment](integrations/jenkins.md) -- [How to run local `Codesandbox` integration for Web IDE Live Preview](integrations/codesandbox.md) +- [How to run local CodeSandbox integration for Web IDE Live Preview](integrations/codesandbox.md) The following integration guides are internal. Some integrations require access to administrative accounts of third-party services and are available only for GitLab team members to contribute to: diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md index dcfcd2e864a..6014ccbfb39 100644 --- a/doc/development/git_object_deduplication.md +++ b/doc/development/git_object_deduplication.md @@ -171,7 +171,7 @@ There are three different things that can go wrong here. #### 1. SQL says repository A belongs to pool P but Gitaly says A has no alternate objects -In this case, we miss out on disk space savings but all RPC's on A +In this case, we miss out on disk space savings but all RPCs on A itself function fine. The next time garbage collection runs on A, the alternates connection gets established in Gitaly. This is done by `Projects::GitDeduplicationService` in GitLab Rails. diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index a570b5dd7eb..a23f1dd2d80 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -56,7 +56,7 @@ they are merged. ### `gitaly-ruby` -It is possible to implement and test RPC's in Gitaly using Ruby code, +It is possible to implement and test RPCs in Gitaly using Ruby code, in [`gitaly-ruby`](https://gitlab.com/gitlab-org/gitaly/tree/master/ruby). This should make it easier to contribute for developers who are less @@ -324,7 +324,7 @@ the integration by using GDK: 1. The state of the flag must be observable. To check it, you must enable it by fetching the Prometheus metrics: - 1. Navigate to GDK's root directory. + 1. Navigate to the GDK root directory. 1. Make sure you have the proper branch checked out for Gitaly. 1. Recompile it with `make gitaly-setup` and restart the service with `gdk restart gitaly`. 1. Make sure your setup is running: `gdk status | grep praefect`. @@ -342,7 +342,7 @@ the integration by using GDK: 1. After you observe the metrics for the new feature flag and it increments, you can enable the new feature: - 1. Navigate to GDK's root directory. + 1. Navigate to the GDK root directory. 1. Start a Rails console: ```shell diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index edf78d5f83d..17b4a28f57d 100644 --- a/doc/development/github_importer.md +++ b/doc/development/github_importer.md @@ -192,7 +192,7 @@ briefly waits for jobs to complete before deciding what the next action should be. For small projects, this may slow down the import process a bit, but it also reduces pressure on the system as a whole. -## Refreshing import JIDs +## Refreshing import job IDs GitLab includes a worker called `Gitlab::Import::StuckProjectImportJobsWorker` that periodically runs and marks project imports as failed if they have been @@ -203,7 +203,7 @@ often we hit the GitHub rate limit (more on this below), but we don't want To prevent this from happening we periodically refresh the expiration time of the import process. This works by storing the JID of the import job in the -database, then refreshing this JID's TTL at various stages throughout the import +database, then refreshing this JID TTL at various stages throughout the import process. This is done by calling `ProjectImportState#refresh_jid_expiration`. By refreshing this TTL we can ensure our import does not get marked as failed so long we're still performing work. diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md index b72f3c14350..85c6653180b 100644 --- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md +++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md @@ -157,7 +157,7 @@ official specifications, but are part of the GitHub and GitLab internal Markdown implementations. These internal extensions are often dependent upon the GitHub or GitLab implementations or environments, and may depend upon metadata which is only available via interacting with those environments. For example, -[GitHub supports GitHub-specific autolinked references](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls), +[GitHub supports GitHub-specific automatically linked references](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls), and [GitLab also supports GitLab-specific references](../../../user/markdown.md#gitlab-specific-references). These may also be implemented by third-party Markdown rendering engines which integrate with @@ -1149,7 +1149,7 @@ These files are Markdown specification files containing examples generated based similar to the `output_spec/spec.txt` and `output_spec/spec.html`, with the following differences: 1. They contain a superset of _all_ examples from - the Commonmark, GitHub Flavored Markdown, and GitLab Flavored Markdown specifications, whereas + the CommonMark, GitHub Flavored Markdown, and GitLab Flavored Markdown specifications, whereas `spec.*` only contains the GLFM specification. This is to provide a single place to refer to all examples when working with [snapshot testing](#markdown-snapshot-testing). 1. They contain _only_ header sections which contain examples. They do not contain any prose-only diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index b561ebc4285..e7e628f5293 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -391,7 +391,7 @@ functionality: This gives us a thin abstraction over underlying implementations that is consistent across Workhorse, Gitaly, and, in future, other Go servers. For example, in the case of `gitlab.com/gitlab-org/labkit/tracing` we can switch -from using `Opentracing` directly to using `Zipkin` or Gokit's own tracing wrapper +from using `Opentracing` directly to using `Zipkin` or the Go kit's own tracing wrapper without changes to the application code, while still keeping the same consistent configuration mechanism (that is, the `GITLAB_TRACING` environment variable). diff --git a/doc/development/image_scaling.md b/doc/development/image_scaling.md index a1a5e9122c6..502a18fecd7 100644 --- a/doc/development/image_scaling.md +++ b/doc/development/image_scaling.md @@ -26,7 +26,7 @@ Whether we allow an image to be rescaled or not is decided by combination of har The hard-coded rules only permit: - [Project, group and user avatars](https://gitlab.com/gitlab-org/gitlab/-/blob/fd08748862a5fe5c25b919079858146ea85843ae/app/controllers/concerns/send_file_upload.rb#L65-67) -- [PNGs or JPEGs](https://gitlab.com/gitlab-org/gitlab/-/blob/5dff8fa3814f2a683d8884f468cba1ec06a60972/lib/gitlab/file_type_detection.rb#L23) +- [PNG or JPEG images](https://gitlab.com/gitlab-org/gitlab/-/blob/5dff8fa3814f2a683d8884f468cba1ec06a60972/lib/gitlab/file_type_detection.rb#L23) - [Specific dimensions](https://gitlab.com/gitlab-org/gitlab/-/blob/5dff8fa3814f2a683d8884f468cba1ec06a60972/app/models/concerns/avatarable.rb#L6) Furthermore, configuration in Workhorse can lead to the image scaler rejecting a request if: diff --git a/doc/development/integrations/codesandbox.md b/doc/development/integrations/codesandbox.md index d7d0ea48db0..b7fe3fbd1c4 100644 --- a/doc/development/integrations/codesandbox.md +++ b/doc/development/integrations/codesandbox.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Set up local CodeSandbox development environment This guide walks through setting up a local [CodeSandbox repository](https://github.com/codesandbox/codesandbox-client) and integrating it with a local GitLab instance. CodeSandbox -is used to power the Web IDE's [Live Preview feature](../../user/project/web_ide/index.md#live-preview). Having a local CodeSandbox setup is useful for debugging upstream issues or +is used to power the Web IDE [Live Preview feature](../../user/project/web_ide/index.md#live-preview). Having a local CodeSandbox setup is useful for debugging upstream issues or creating upstream contributions like [this one](https://github.com/codesandbox/codesandbox-client/pull/5137). ## Initial setup @@ -43,7 +43,7 @@ Before using CodeSandbox with your local GitLab instance, you must: GitLab integrates with two parts of CodeSandbox: - An npm package called `smooshpack` (called `sandpack` in the `codesandbox-client` project). - This exposes an entrypoint for us to kick off Codesandbox's bundler. + This exposes an entrypoint for us to kick off CodeSandbox's bundler. - A server that houses CodeSandbox assets for bundling and previewing. This is hosted on a separate server for security. diff --git a/doc/development/integrations/index.md b/doc/development/integrations/index.md index 2639da818c6..8c715a0459a 100644 --- a/doc/development/integrations/index.md +++ b/doc/development/integrations/index.md @@ -58,7 +58,7 @@ end `Integration.prop_accessor` installs accessor methods on the class. Here we would have `#url`, `#url=` and `#url_changed?`, to manage the `url` field. Fields stored in `Integration#properties` should be accessed by these accessors directly on the model, just like other ActiveRecord attributes. -You should always access the properties through their getters, and not interact with the `properties` hash directly. +You should always access the properties through their `getters`, and not interact with the `properties` hash directly. You **must not** write to the `properties` hash, you **must** use the generated setter method instead. Direct writes to this hash are not persisted. diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index d4215662db4..a03667be7cc 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -68,7 +68,7 @@ If the app install failed, you might need to delete `jira_connect_installations` #### Not authorized to access the file -If you use Gitpod and you get an error about Jira not being able to access the descriptor file, you might need to make the GDK's port public by following these steps: +If you use Gitpod and you get an error about Jira not being able to access the descriptor file, you might need to make the GDK port public by following these steps: 1. Open your GitLab workspace in Gitpod. 1. When the GDK is running, select **Ports** in the bottom-right corner. diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 6e505fa0d19..a482b16e9cb 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -338,7 +338,7 @@ is concurrently accessed and modified by other processes, acquiring the lock may a while. The lock request is waiting in a queue and it may also block other queries on the `users` table once it has been enqueued. -More information about PostgresSQL locks: [Explicit Locking](https://www.postgresql.org/docs/current/explicit-locking.html) +More information about PostgreSQL locks: [Explicit Locking](https://www.postgresql.org/docs/current/explicit-locking.html) For stability reasons, GitLab.com has a specific [`statement_timeout`](../user/gitlab_com/index.md#postgresql) set. When the migration is invoked, any database query has @@ -813,7 +813,7 @@ in the `namespaces` table. Only when creating a new column with a default, all t 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 rewriting the table when a new column with a default value is added. +was introduced on PostgreSQL 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!`. diff --git a/doc/development/packages/dependency_proxy.md b/doc/development/packages/dependency_proxy.md index d5cc219cba0..1386889a43f 100644 --- a/doc/development/packages/dependency_proxy.md +++ b/doc/development/packages/dependency_proxy.md @@ -143,7 +143,7 @@ Management of file uploads and caching happens in [Workhorse](../workhorse/index [`POST` routes](https://gitlab.com/gitlab-org/gitlab/-/blob/3f76455ac9cf90a927767e55c837d6b07af818df/config/routes/group.rb#L170-173) that we have for the Dependency Proxy. -The [send_dependency](https://gitlab.com/gitlab-org/gitlab/-/blob/7359d23f4e078479969c872924150219c6f1665f/app/helpers/workhorse_helper.rb#L46-53) +The [`send_dependency`](https://gitlab.com/gitlab-org/gitlab/-/blob/7359d23f4e078479969c872924150219c6f1665f/app/helpers/workhorse_helper.rb#L46-53) method makes a request to Workhorse including the previously fetched JWT from the external registry. Workhorse then can use that token to request the manifest or blob the user originally requested. The Workhorse code lives in [`workhorse/internal/dependencyproxy/dependencyproxy.go`](https://gitlab.com/gitlab-org/gitlab/-/blob/b8f44a8f3c26efe9932c2ada2df75ef7acb8417b/workhorse/internal/dependencyproxy/dependencyproxy.go#L4). diff --git a/doc/development/pages/index.md b/doc/development/pages/index.md index 6ee8a9ac433..5e56264330a 100644 --- a/doc/development/pages/index.md +++ b/doc/development/pages/index.md @@ -178,7 +178,7 @@ The `redirect-uri` must not contain any GitLab Pages site domain. auth-redirect-uri=http://pages.gdk.test:3010/auth # the authentication callback url for GitLab Pages ``` -1. If running Pages inside the GDK, you can use GDK's `protected_config_files` section under `gdk` in +1. If running Pages inside the GDK, you can use GDK `protected_config_files` section under `gdk` in your `gdk.yml` to avoid getting `gitlab-pages.conf` configuration rewritten: ```yaml diff --git a/doc/development/product_qualified_lead_guide/index.md b/doc/development/product_qualified_lead_guide/index.md index 89a05d59fc9..f8cd7fd48b9 100644 --- a/doc/development/product_qualified_lead_guide/index.md +++ b/doc/development/product_qualified_lead_guide/index.md @@ -17,7 +17,7 @@ A hand-raise PQL is a user who requests to speak to sales from within the produc 1. Set up CustomersDot using the [normal install instructions](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/staging/doc/setup/installation_steps.md). 1. Set the `CUSTOMER_PORTAL_URL` environment variable to your local (or ngrok) URL of your CustomersDot instance. -1. Place `export CUSTOMER_PORTAL_URL='https://XXX.ngrok.io/'` in your shell rc script (`~/.zshrc` or `~/.bash_profile` or `~/.bashrc`) and restart GDK. +1. Place `export CUSTOMER_PORTAL_URL='https://XXX.ngrok.io/'` in your shell `rc` script (`~/.zshrc` or `~/.bash_profile` or `~/.bashrc`) and restart GDK. 1. Enter the credentials on CustomersDot development to Platypus in your `/config/secrets.yml` and restart. Credentials for the Platypus Staging are in the 1Password Growth vault. The URL for staging is `https://staging.ci.nexus.gitlabenvironment.cloud`. ```yaml @@ -144,7 +144,7 @@ sequenceDiagram ``` -#### Trial lead flow on CustomersDot (sync_to_gl) +#### Trial lead flow on CustomersDot (`sync_to_gl`) ```mermaid sequenceDiagram diff --git a/doc/development/projections.md b/doc/development/projections.md index 49480981d8d..7c727fc0901 100644 --- a/doc/development/projections.md +++ b/doc/development/projections.md @@ -24,7 +24,7 @@ You can find a basic list of projection options in - vim - [vim-projectionist](https://github.com/tpope/vim-projectionist) -- VSCode +- VS Code - [Alternate File](https://marketplace.visualstudio.com/items?itemName=will-wow.vscode-alternate-file) - [projectionist](https://github.com/jarsen/projectionist) - [`jumpto`](https://github.com/gmdayley/jumpto) diff --git a/doc/development/reactive_caching.md b/doc/development/reactive_caching.md index 3239748193f..9e3b1f58abe 100644 --- a/doc/development/reactive_caching.md +++ b/doc/development/reactive_caching.md @@ -208,7 +208,7 @@ There are some `class_attribute` options which can be tweaked. self.reactive_cache_key = ->(integration) { [integration.class.model_name.singular, integration.project_id] } ``` - If your reactive_cache_key is exactly like the above, you can use the existing + If your `reactive_cache_key` is exactly like the above, you can use the existing `Integrations::ReactivelyCached` concern instead. #### `self.reactive_cache_lease_timeout` diff --git a/doc/development/sec/index.md b/doc/development/sec/index.md index fc13c960451..3f52020701f 100644 --- a/doc/development/sec/index.md +++ b/doc/development/sec/index.md @@ -102,15 +102,15 @@ After being [merged](../integrations/secure.md#tracking-and-merging-vulnerabilit ### Analyzer vulnerability translation -In the case of SAST's semgrep analyzer, there is a secondary identifier of particular importance: the identifier linking the report’s vulnerability -to the legacy analyzer (that is, bandit or eslint). +In the case of the SAST Semgrep analyzer, there is a secondary identifier of particular importance: the identifier linking the report’s vulnerability +to the legacy analyzer (that is, bandit or ESLint). To [enable vulnerability translation](../../user/application_security/sast/analyzers.md#vulnerability-translation) -the semgrep analyzer relies on a secondary identifier exactly matching the primary identifier of the legacy analyzer. +the Semgrep analyzer relies on a secondary identifier exactly matching the primary identifier of the legacy analyzer. For example, when [`eslint`](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) was previously used to generate vulnerability records, the [`semgrep`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) analyzer must produce an identifier collection containing the -original eslint primary identifier. +original ESLint primary identifier. Given the original `eslint` report: @@ -131,7 +131,7 @@ Given the original `eslint` report: } ``` -The corresponding semgrep report must contain the `eslint_rule_id`: +The corresponding Semgrep report must contain the `eslint_rule_id`: ```json { diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index 471c93c3baa..bccdda9ca04 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -1209,7 +1209,7 @@ These types of bugs are often seen in environments which allow multi-threading a ### Examples -**Example 1:** you have a model which accepts a URL as input. When the model is created you verify that the URL's host resolves to a public IP address, to prevent attackers making internal network calls. But DNS records can change ([DNS rebinding](#server-side-request-forgery-ssrf)]). An attacker updates the DNS record to `127.0.0.1`, and when your code resolves those URL's host it results in sending a potentially malicious request to a server on the internal network. The property was valid at the "time of check", but invalid and malicious at "time of use". +**Example 1:** you have a model which accepts a URL as input. When the model is created you verify that the URL host resolves to a public IP address, to prevent attackers making internal network calls. But DNS records can change ([DNS rebinding](#server-side-request-forgery-ssrf)]). An attacker updates the DNS record to `127.0.0.1`, and when your code resolves those URL host it results in sending a potentially malicious request to a server on the internal network. The property was valid at the "time of check", but invalid and malicious at "time of use". GitLab-specific example can be found in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214401) where, although `Gitlab::UrlBlocker.validate!` was called, the returned value was not used. This made it vulnerable to TOCTOU bug and SSRF protection bypass through [DNS rebinding](#server-side-request-forgery-ssrf). The fix was to [use the validated IP address](https://gitlab.com/gitlab-org/gitlab/-/commit/7af8abd4df9a98f7a1ae7c4ec9840d0a7a8c684d). diff --git a/doc/development/service_ping/metrics_dictionary.md b/doc/development/service_ping/metrics_dictionary.md index f7abf7b99fa..25895d732e4 100644 --- a/doc/development/service_ping/metrics_dictionary.md +++ b/doc/development/service_ping/metrics_dictionary.md @@ -55,7 +55,7 @@ Each metric is defined in a separate YAML file consisting of a number of fields: | `options` | no | `object`: options information needed to calculate the metric value. | | `skip_validation` | no | This should **not** be set. [Used for imported metrics until we review, update and make them valid](https://gitlab.com/groups/gitlab-org/-/epics/5425). | -### Metric key_path +### Metric `key_path` The `key_path` of the metric is the location in the JSON Service Ping payload. @@ -108,7 +108,7 @@ Metric definitions can have one of the following statuses: - `broken`: Metric reports broken data (for example, -1 fallback), or does not report data at all. A metric marked as `broken` must also have the `repair_issue_url` attribute. - `removed`: Metric was removed, but it may appear in Service Ping payloads sent from instances running on older versions of GitLab. -### Metric value_type +### Metric `value_type` Metric definitions can have one of the following values for `value_type`: @@ -120,7 +120,7 @@ In general, we avoid complex objects and prefer one of the `boolean`, `number`, An example of a metric that uses `value_type: object` is `topology` (`/config/metrics/settings/20210323120839_topology.yml`), which has a related schema in `/config/metrics/objects_schemas/topology_schema.json`. -### Metric time_frame +### Metric `time_frame` - `7d`: The metric data applies to the most recent 7-day interval. For example, the following metric counts the number of users that create epics over a 7-day interval: `ee/config/metrics/counts_7d/20210305145820_g_product_planning_epic_created_weekly.yml`. - `28d`: The metric data applies to the most recent 28-day interval. For example, the following metric counts the number of unique users that create issues over a 28-day interval: `config/metrics/counts_28d/20210216181139_issues.yml`. diff --git a/doc/development/sidekiq/idempotent_jobs.md b/doc/development/sidekiq/idempotent_jobs.md index 80c6c403549..1487677ed75 100644 --- a/doc/development/sidekiq/idempotent_jobs.md +++ b/doc/development/sidekiq/idempotent_jobs.md @@ -189,7 +189,7 @@ that can tolerate some duplication. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69372) in GitLab 14.3. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/338350) in GitLab 14.4. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338350) in GitLab 14.6. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/346598) in GitLab 14.9. [Feature flag preserve_latest_wal_locations_for_idempotent_jobs](https://gitlab.com/gitlab-org/gitlab/-/issues/346598) removed. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/346598) in GitLab 14.9. [Feature flag `preserve_latest_wal_locations_for_idempotent_jobs`](https://gitlab.com/gitlab-org/gitlab/-/issues/346598) removed. The deduplication always take into account the latest binary replication pointer, not the first one. This happens because we drop the same job scheduled for the second time and the Write-Ahead Log (WAL) is lost. diff --git a/doc/development/sidekiq/index.md b/doc/development/sidekiq/index.md index 979432a2e5b..c9d783377bd 100644 --- a/doc/development/sidekiq/index.md +++ b/doc/development/sidekiq/index.md @@ -14,7 +14,7 @@ information on administering GitLab, see [configuring Sidekiq](../../administrat There are pages with additional detail on the following topics: 1. [Compatibility across updates](compatibility_across_updates.md) -1. [Job idempotency and job deduplication](idempotent_jobs.md) +1. [Job idempotence and job deduplication](idempotent_jobs.md) 1. [Limited capacity worker: continuously performing work with a specified concurrency](limited_capacity_worker.md) 1. [Logging](logging.md) 1. [Worker attributes](worker_attributes.md) diff --git a/doc/development/snowplow/index.md b/doc/development/snowplow/index.md index 8d05e05e592..32628744a23 100644 --- a/doc/development/snowplow/index.md +++ b/doc/development/snowplow/index.md @@ -17,7 +17,7 @@ Snowplow is an enterprise-grade marketing and Product Intelligence platform that - **Data modeling** joins event-level data with other data sets, aggregates them into smaller data sets, and applies business logic. This produces a clean set of tables for data analysis. We use data models for Redshift and Looker. - **Analytics** are performed on Snowplow events or on aggregate tables. - + ## Enable Snowplow tracking diff --git a/doc/development/testing_guide/end_to_end/feature_flags.md b/doc/development/testing_guide/end_to_end/feature_flags.md index b9a36bfb60c..e473b158087 100644 --- a/doc/development/testing_guide/end_to_end/feature_flags.md +++ b/doc/development/testing_guide/end_to_end/feature_flags.md @@ -30,7 +30,7 @@ feature flag is under test. - Format: `feature_flag: { name: 'feature_flag_name', scope: :project }` - When `scope` is set to `:global`, the test will be **skipped on all live .com environments**. This is to avoid issues with feature flag changes affecting other tests or users on that environment. -- When `scope` is set to any other value (such as `:project`, `:group` or `:user`), or if no `scope` is specified, the test will only be **skipped on canary, production, and preprod**. +- When `scope` is set to any other value (such as `:project`, `:group` or `:user`), or if no `scope` is specified, the test will only be **skipped on canary, production, and pre-production**. This is due to the fact that administrator access is not available there. **WARNING:** You are strongly advised to first try and [enable feature flags only for a group, project, user](../../feature_flags/index.md#feature-actors), diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md index 5fbf2ffbcde..6a599ce9a50 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -155,7 +155,7 @@ In our case, `data-qa-selector="login_field"`, `data-qa-selector="password_field Things to note: -- The name of the element and the `qa_selector` must match and be snake_cased +- The name of the element and the `qa_selector` must match and be snake cased - If the element appears on the page unconditionally, add `required: true` to the element. See [Dynamic element validation](dynamic_element_validation.md) - You may see `.qa-selector` classes in existing Page Objects. We should prefer the [`data-qa-selector`](#data-qa-selector-vs-qa-selector) diff --git a/doc/development/testing_guide/end_to_end/troubleshooting.md b/doc/development/testing_guide/end_to_end/troubleshooting.md index e0925cb71f4..b4c47b90f0b 100644 --- a/doc/development/testing_guide/end_to_end/troubleshooting.md +++ b/doc/development/testing_guide/end_to_end/troubleshooting.md @@ -59,7 +59,7 @@ Net::ReadTimeout: Net::ReadTimeout with #<TCPSocket:(closed)> ``` This error can happen if GitLab runs on an address that does not resolve from -`localhost`. For example, if you set GDK's `hostname` +`localhost`. For example, if you set the GDK `hostname` [to a specific local IP address](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/run_qa_against_gdk.md#run-qa-tests-against-your-gdk-setup), you must use that IP address instead of `localhost` in the command. For example, if your IP is `192.168.0.12`: diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 647fb94c4f6..d925e04266c 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -1165,7 +1165,7 @@ By now you've probably heard of [Jest snapshot tests](https://jestjs.io/docs/sna To use them within GitLab, there are a few guidelines that should be highlighted: - Treat snapshots as code -- Don't think of a snapshot file as a Blackbox +- Don't think of a snapshot file as a black box - Care for the output of the snapshot, otherwise, it's not providing any real value. This will usually involve reading the generated snapshot file as you would read any other piece of code Think of a snapshot test as a simple way to store a raw `String` representation of what you've put into the item being tested. This can be used to evaluate changes in a component, a store, a complex piece of generated output, etc. You can see more in the list below for some recommended `Do's and Don'ts`. @@ -1175,7 +1175,7 @@ Jest provides a great set of docs on [best practices](https://jestjs.io/docs/sna ### How does a snapshot work? -A snapshot is purely a stringified version of what you ask to be tested on the lefthand side of the function call. This means any kind of changes you make to the formatting of the string has an impact on the outcome. This process is done by leveraging serializers for an automatic transform step. For Vue this is already taken care of by leveraging the `vue-jest` package, which offers the proper serializer. +A snapshot is purely a stringified version of what you ask to be tested on the left-hand side of the function call. This means any kind of changes you make to the formatting of the string has an impact on the outcome. This process is done by leveraging serializers for an automatic transform step. For Vue this is already taken care of by leveraging the `vue-jest` package, which offers the proper serializer. Should the outcome of your spec be different from what is in the generated snapshot file, you'll be notified about it by a failing test in your test suite. diff --git a/doc/development/uploads/working_with_uploads.md b/doc/development/uploads/working_with_uploads.md index 92d0f45bd4b..a3951fb4c7e 100644 --- a/doc/development/uploads/working_with_uploads.md +++ b/doc/development/uploads/working_with_uploads.md @@ -26,7 +26,7 @@ stored. When you create a new Uploader class you are deciding where to store the feature. First of all, ask yourself if you need a new Uploader class. It is OK -to use the same Uploader class for different mountpoints or different +to use the same Uploader class for different mount points or different models. If you do want or need your own Uploader class then you should make it @@ -160,8 +160,8 @@ we modified it. The central concept of CarrierWave is the **Uploader** class. The Uploader defines where files get stored, and optionally contains validation and processing logic. To use an Uploader you must associate -it with a text column on an ActiveRecord model. This called "mounting" -and the column is called the "mountpoint". For example: +it with a text column on an ActiveRecord model. This is called "mounting" +and the column is called `mountpoint`. For example: ```ruby class Project < ApplicationRecord @@ -179,12 +179,12 @@ The directory `/var/opt/gitlab/gitlab-rails/uploads/-/system/project/avatar/123/` was chosen by the Uploader using among others configuration (`/var/opt/gitlab/gitlab-rails/uploads`), the model name (`project`), -the model ID (`123`) and the mountpoint (`avatar`). +the model ID (`123`) and the mount point (`avatar`). > The Uploader determines the individual storage directory of your -> upload. The mountpoint column in your model contains the filename. +> upload. The `mountpoint` column in your model contains the filename. -You never access the mountpoint column directly because CarrierWave +You never access the `mountpoint` column directly because CarrierWave defines a getter and setter on your model that operates on file handle objects. @@ -213,7 +213,7 @@ CarrierWave has 2 storage engines: |CarrierWave class|GitLab name|Description| |---|---|---| -|`CarrierWave::Storage::File`|`ObjectStorage::Store::LOCAL` |Local files, accessed through the Ruby stdlib| +|`CarrierWave::Storage::File`|`ObjectStorage::Store::LOCAL` |Local files, accessed through the Ruby `stdlib` | | `CarrierWave::Storage::Fog`|`ObjectStorage::Store::REMOTE`|Cloud files, accessed through the [Fog gem](https://github.com/fog/fog)| GitLab uses both of these engines, depending on configuration. @@ -227,8 +227,8 @@ storage engine file by file. An Uploader is associated with two storage areas: regular storage and cache storage. Each has its own storage engine. If you assign a file -to a mountpoint setter (`project.avatar = -File.open('/tmp/tanuki.png')`) you will copy/move the file to cache +to a mount point setter (`project.avatar = File.open('/tmp/tanuki.png')`) +you will copy/move the file to cache storage as a side effect via the `cache!` method. To persist the file you must somehow call the `store!` method. This either happens via [ActiveRecord callbacks](https://github.com/carrierwaveuploader/carrierwave/blob/v1.3.2/lib/carrierwave/orm/activerecord.rb#L55) diff --git a/doc/development/value_stream_analytics.md b/doc/development/value_stream_analytics.md index ace921b3978..2d5f33b5dae 100644 --- a/doc/development/value_stream_analytics.md +++ b/doc/development/value_stream_analytics.md @@ -71,7 +71,7 @@ which are always available to the end-users regardless of the subscription. ### Value streams Value streams are container objects for the stages. There can be multiple value streams per group -focusing on different aspects of the Dev Ops lifecycle. +focusing on different aspects of the DevOps lifecycle. ### Events diff --git a/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md b/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md index c477b3d9015..5bcadc6f39b 100644 --- a/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md +++ b/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md @@ -54,7 +54,7 @@ database with a minimal development effort. ### Example configuration - + In this example, two independent value streams are set up for two teams that are using different development workflows within the `Test Group` (top-level namespace). diff --git a/doc/development/work_items.md b/doc/development/work_items.md index a417e1d1349..90e454bec85 100644 --- a/doc/development/work_items.md +++ b/doc/development/work_items.md @@ -54,7 +54,7 @@ To avoid confusion and ensure communication is efficient, we will use the follow | work item view | The new frontend view that renders work items of any type | | | | legacy issue view | The existing view used to render issues and incidents | | | | issue | The existing issue model | | | -| issuable | Any model currently using the issueable module (issues, epics and MRs) | _Incidents are an **issuable**_ | _Incidents are a **work item type**_ | +| issuable | Any model currently using the issuable module (issues, epics and MRs) | _Incidents are an **issuable**_ | _Incidents are a **work item type**_ | | widget | A UI element to present or allow interaction with specific work item data | | | Some terms have been used in the past but have since become confusing and are now discouraged. @@ -92,7 +92,7 @@ NOTE: At first, defining a WIT will only be possible at the root-level group, which would then be inherited by subgroups. We will investigate the possibility of defining new WITs at subgroup levels at a later iteration. -### Introducing work_item_types table +### Introducing `work_item_types` table For example, suppose there are three root-level groups with IDs: `11`, `12`, and `13`. Also, assume the following base types: `issue: 0`, `incident: 1`, `test_case: 2`. @@ -228,7 +228,7 @@ So, migrating epics to a work item type requires providing feature parity betwee The main missing features are: -- Get WIs to the group level. This is dependent on [Consolidate Groups and Projects](https://gitlab.com/gitlab-org/architecture/tasks/-/issues/7) +- Get work items to the group level. This is dependent on [Consolidate Groups and Projects](https://gitlab.com/gitlab-org/architecture/tasks/-/issues/7) initiative. - A hierarchy widget: the ability to structure work items into hierarchies. - Inherited date widget. diff --git a/doc/development/work_items_widgets.md b/doc/development/work_items_widgets.md index 89602d969e6..ba15a3f0163 100644 --- a/doc/development/work_items_widgets.md +++ b/doc/development/work_items_widgets.md @@ -80,7 +80,7 @@ mutation { ``` -### Widget's responsibility and structure +### Widget responsibility and structure A widget is responsible for displaying and updating a single attribute, such as title, description, or labels. Widgets must support any type of work item. diff --git a/doc/development/workhorse/configuration.md b/doc/development/workhorse/configuration.md index 82e44a6f995..9fc106b8f04 100644 --- a/doc/development/workhorse/configuration.md +++ b/doc/development/workhorse/configuration.md @@ -162,7 +162,7 @@ addr = "localhost:9229" max_version = "tls1.3" ``` -## Interaction of authBackend and authSocket +## Interaction of `authBackend` and `authSocket` The interaction between `authBackend` and `authSocket` can be confusing. If `authSocket` is set, it overrides the host portion of `authBackend`, but not @@ -170,7 +170,7 @@ the relative path. In table form: -| authBackend | authSocket | Workhorse connects to | Rails relative URL | +| `authBackend` | `authSocket` | Workhorse connects to | Rails relative URL | |--------------------------------|-------------------|-----------------------|--------------------| | unset | unset | `localhost:8080` | `/` | | `http://localhost:3000` | unset | `localhost:3000` | `/` | |