diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-14 21:10:59 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-14 21:10:59 +0300 |
commit | ea3306a15e945e694afba62dc93b17500ffaec7f (patch) | |
tree | aa444f7fe503e5650bfdb6500ed428b4619ff37b /doc | |
parent | 8106ac487c3b52471e2ca894c65c13162c2fb1a8 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/administration/geo/disaster_recovery/index.md | 73 | ||||
-rw-r--r-- | doc/administration/housekeeping.md | 17 | ||||
-rw-r--r-- | doc/api/epic_links.md | 2 | ||||
-rw-r--r-- | doc/api/groups.md | 22 | ||||
-rw-r--r-- | doc/api/personal_access_tokens.md | 3 | ||||
-rw-r--r-- | doc/ci/environments/deployment_safety.md | 69 | ||||
-rw-r--r-- | doc/ci/examples/semantic-release.md | 2 | ||||
-rw-r--r-- | doc/ci/pipeline_editor/index.md | 19 | ||||
-rw-r--r-- | doc/development/agent/identity.md | 4 | ||||
-rw-r--r-- | doc/development/packages.md | 18 | ||||
-rw-r--r-- | doc/development/usage_ping.md | 104 | ||||
-rw-r--r-- | doc/user/group/iterations/index.md | 16 | ||||
-rw-r--r-- | doc/user/packages/dependency_proxy/index.md | 3 | ||||
-rw-r--r-- | doc/user/packages/nuget_repository/index.md | 8 | ||||
-rw-r--r-- | doc/user/profile/notifications.md | 3 | ||||
-rw-r--r-- | doc/user/project/quick_actions.md | 3 | ||||
-rw-r--r-- | doc/user/project/web_ide/index.md | 39 | ||||
-rw-r--r-- | doc/user/search/index.md | 46 | ||||
-rw-r--r-- | doc/user/snippets.md | 26 |
19 files changed, 368 insertions, 109 deletions
diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 544dacc707a..2b0a3e2f114 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -181,7 +181,7 @@ secondary. If the node is paused, be sure to resume before promoting. This issue has been fixed in GitLab 13.4 and later. WARNING: - If the secondary node [has been paused](../../geo/index.md#pausing-and-resuming-replication), this performs +If the secondary node [has been paused](../../geo/index.md#pausing-and-resuming-replication), this performs a point-in-time recovery to the last known state. Data that was created on the primary while the secondary was paused will be lost. @@ -220,6 +220,75 @@ Data that was created on the primary while the secondary was paused will be lost previously for the **secondary**. 1. Success! The **secondary** has now been promoted to **primary**. +#### Promoting a **secondary** node with a Patroni standby cluster + +The `gitlab-ctl promote-to-primary-node` command cannot be used yet in +conjunction with a Patroni standby cluster, as it can only +perform changes on a **secondary** with only a single machine. Instead, you must +do this manually. + +WARNING: +In GitLab 13.2 and 13.3, promoting a secondary node to a primary while the +secondary is paused fails. Do not pause replication before promoting a +secondary. If the node is paused, be sure to resume before promoting. This +issue has been fixed in GitLab 13.4 and later. + +WARNING: +If the secondary node [has been paused](../../geo/index.md#pausing-and-resuming-replication), this performs +a point-in-time recovery to the last known state. +Data that was created on the primary while the secondary was paused will be lost. + +1. SSH in to the Standby Leader database node in the **secondary** and trigger PostgreSQL to + promote to read-write: + + ```shell + sudo gitlab-ctl promote-db + ``` + +1. Disable Patroni auto-failover: + + ```shell + sudo gitlab-ctl patroni pause + ``` + +1. Edit `/etc/gitlab/gitlab.rb` on every application and Sidekiq nodes in the secondary to reflect its new status as primary by removing any lines that enabled the `geo_secondary_role`: + + ```ruby + ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. + geo_secondary_role['enable'] = true + + ## In 11.5+ documentation, the role was enabled as follows. Remove this line. + roles ['geo_secondary_role'] + ``` + +1. Edit `/etc/gitlab/gitlab.rb` on every Patroni node in the secondary to disable the standby cluster: + + ```ruby + patroni['standby_cluster']['enable'] = false + ``` + +1. Reconfigure GitLab on each machine for the changes to take effect: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Resume Patroni auto-failover: + + ```shell + sudo gitlab-ctl patroni resume + ``` + +1. Promote the **secondary** to **primary**. SSH into a single application server and execute: + + ```shell + sudo gitlab-rake geo:set_secondary_as_primary + ``` + +1. Verify you can connect to the newly promoted **primary** using the URL used previously for the **secondary**. + +1. Success! The **secondary** has now been promoted to **primary**. + #### Promoting a **secondary** node with an external PostgreSQL database The `gitlab-ctl promote-to-primary-node` command cannot be used in conjunction with @@ -278,7 +347,7 @@ required: 1. Verify you can connect to the newly promoted **primary** site using the URL used previously for the **secondary** site. -Success! The **secondary** site has now been promoted to **primary**. +1. Success! The **secondary** site has now been promoted to **primary**. ### Step 4. (Optional) Updating the primary domain DNS record diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index 90d2f0d916d..eedd0fb8293 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -40,3 +40,20 @@ from your project on the same schedule as the `git gc` operation, freeing up sto You can find this option under your project's **Settings > General > Advanced**. ![Housekeeping settings](img/housekeeping_settings.png) + +## How housekeeping handles pool repositories + +Housekeeping for pool repositories is handled differently from standard repositories. +It is ultimately performed by the Gitaly RPC `FetchIntoObjectPool`. + +This is the current call stack by which it is invoked: + +1. `Projects::HousekeepingService#execute_gitlab_shell_gc` +1. `GitGarbageCollectWorker#perform` +1. `Projects::GitDeduplicationService#fetch_from_source` +1. `ObjectPool#fetch` +1. `ObjectPoolService#fetch` +1. `Gitaly::FetchIntoObjectPoolRequest` + +To manually invoke it from a Rails console, if needed, you can call `project.pool_repository.object_pool.fetch`. +This is a potentially long-running task, though Gitaly will timeout in about 8 hours. diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index 319d1a1ee9b..cabab18ed71 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -76,7 +76,7 @@ Example response: Creates an association between two epics, designating one as the parent epic and the other as the child epic. A parent epic can have multiple child epics. If the new child epic already belonged to another epic, it is unassigned from that previous parent. ```plaintext -POST /groups/:id/epics/:epic_iid/epics +POST /groups/:id/epics/:epic_iid/epics/:child_epic_id ``` | Attribute | Type | Required | Description | diff --git a/doc/api/groups.md b/doc/api/groups.md index abd4a7ecdea..eb255f8de00 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -766,7 +766,6 @@ Parameters: | `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). Default to the global level default branch protection setting. | | `shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | | `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | -| `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | ### Options for `default_branch_protection` @@ -778,16 +777,6 @@ The `default_branch_protection` attribute determines whether developers and main | `1` | Partial protection. Developers and maintainers can: <br>- Push new commits | | `2` | Full protection. Only maintainers can: <br>- Push new commits | -### Options for `shared_runners_setting` - -The `shared_runners_setting` attribute determines whether shared runners are enabled for a group's subgroups and projects. - -| Value | Description | -|-------|-------------------------------------------------------------------------------------------------------------| -| `enabled` | Enables shared runners for all projects and subgroups in this group. | -| `disabled_with_override` | Disables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting. | -| `disabled_and_unoverridable` | Disables shared runners for all projects and subgroups in this group, and prevents subgroups from overriding this setting. | - ## New Subgroup This is similar to creating a [New group](#new-group). You need the `parent_id` from the [List groups](#list-groups) call. You can then enter the desired: @@ -852,6 +841,7 @@ PUT /groups/:id | `shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | | `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | | `prevent_forking_outside_group` | boolean | no | **(PREMIUM)** When enabled, users can **not** fork projects from this group to external namespaces +| `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | NOTE: The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). @@ -941,6 +931,16 @@ with Rails console access to run the following command: Feature.disable(:limit_projects_in_groups_api) ``` +### Options for `shared_runners_setting` + +The `shared_runners_setting` attribute determines whether shared runners are enabled for a group's subgroups and projects. + +| Value | Description | +|-------|-------------------------------------------------------------------------------------------------------------| +| `enabled` | Enables shared runners for all projects and subgroups in this group. | +| `disabled_with_override` | Disables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting. | +| `disabled_and_unoverridable` | Disables shared runners for all projects and subgroups in this group, and prevents subgroups from overriding this setting. | + ## Remove group Only available to group owners and administrators. diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 535f33ece4a..ca0ac3522c3 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -70,7 +70,8 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ## Revoke a personal access token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216004) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216004) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.6. Revoke a personal access token. diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 97db7c90c8b..4dac076ffb7 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -14,6 +14,9 @@ You can: - [Restrict write-access to a critical environment](#restrict-write-access-to-a-critical-environment) - [Prevent deployments during deploy freeze windows](#prevent-deployments-during-deploy-freeze-windows) +- [Set appropriate roles to your project](#setting-appropriate-roles-to-your-project) +- [Protect production secrets](#protect-production-secrets) +- [Separate project for deployments](#separate-project-for-deployments) If you are using a continuous deployment workflow and want to ensure that concurrent deployments to the same environment do not happen, you should enable the following options: @@ -38,8 +41,8 @@ For example: ```yaml deploy: - script: deploy-to-prod - resource_group: prod + script: deploy-to-prod + resource_group: prod ``` Example of a problematic pipeline flow **before** using the resource group: @@ -89,6 +92,56 @@ If you want to prevent deployments for a particular period, for example during a vacation period when most employees are out, you can set up a [Deploy Freeze](../../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze). During a deploy freeze period, no deployment can be executed. This is helpful to ensure that deployments do not happen unexpectedly. + +## Setting appropriate roles to your project + +GitLab supports several different roles that can be assigned to your project members. See +[Project members permissions](../../user/permissions.md#project-members-permissions) +for an explanation of these roles and the permissions of each. + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=Mq3C1KveDc0">How to secure your CD pipelines</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/Mq3C1KveDc0" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +## Protect production secrets + +Production secrets are needed to deploy successfully. For example, when deploying to the cloud, +cloud providers require these secrets to connect to their services. In the project settings, you can +define and protect environment variables for these secrets. [Protected variables](../variables/README.md#protect-a-custom-variable) +are only passed to pipelines running on [protected branches](../../user/project/protected_branches.md) +or [protected tags](../../user/project/protected_tags.md). +The other pipelines don't get the protected variable. You can also +[scope variables to specific environments](../variables/where_variables_can_be_used.md#variables-with-an-environment-scope). +We recommend that you use protected variables on protected environments to make sure that the +secrets aren't exposed unintentionally. You can also define production secrets on the +[runner side](../runners/README.md#prevent-runners-from-revealing-sensitive-information). +This prevents other maintainers from reading the secrets and makes sure that the runner only runs on +protected branches. + +For more information, see [pipeline security](../pipelines/index.md#pipeline-security-on-protected-branches). + +## Separate project for deployments + +All project maintainers have access to production secrets. If you need to limit the number of users +that can deploy to a production environment, you can create a separate project and configure a new +permission model that isolates the CD permissions from the original project and prevents the +original project's maintainers from accessing the production secret and CD configuration. You can +connect the CD project to your development projects by using [multi-project pipelines](../multi_project_pipelines.md). + +## Protect `gitlab-ci.yml` from change + +A `.gitlab-ci.yml` may contain rules to deploy an application to the production server. This +deployment usually runs automatically after pushing a merge request. To prevent developers from +changing the `gitlab-ci.yml`, you can define it in a different repository. The configuration can +reference a file in another project with a completely different set of permissions (similar to +[separating a project for deployments](#separate-project-for-deployments)). +In this scenario, the `gitlab-ci.yml` is publicly accessible, but can only be edited by users with +appropriate permissions in the other project. + +For more information, see [Custom CI configuration path](../pipelines/settings.md#custom-ci-configuration-path). ## Troubleshooting @@ -99,15 +152,13 @@ If you have multiple jobs for the same environment (including non-deployment job ```yaml build:service-a: - environment: - name: production - + environment: + name: production + build:service-b: - environment: - name: production + environment: + name: production ``` The [Skip outdated deployment jobs](../pipelines/settings.md#skip-outdated-deployment-jobs) might not work well with this configuration, and must be disabled. - -There is a [plan to introduce a new annotation for environments](https://gitlab.com/gitlab-org/gitlab/-/issues/208655) to address this issue. diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md index 70d29b739b1..037faaf66a2 100644 --- a/doc/ci/examples/semantic-release.md +++ b/doc/ci/examples/semantic-release.md @@ -35,7 +35,7 @@ You can also view or fork the complete [example source](https://gitlab.com/gitla } ``` -1. Update the `files` key with glob pattern(s) that selects all files that should be included in the published module. More information about `files` can be found [in NPM's documentation](https://docs.npmjs.com/cli/v6/configuring-npm/package-json#files). +1. Update the `files` key with glob pattern(s) that selects all files that should be included in the published module. More information about `files` can be found [in NPM's documentation](https://docs.npmjs.com/cli/v6/configuring-npm/package-json/#files). 1. Add a `.gitignore` file to the project to avoid committing `node_modules`: diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 2d03ceb264f..61b8e289509 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -59,8 +59,9 @@ reflected in the CI lint. It displays the same results as the existing [CI Lint > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241722) in GitLab 13.5. > - [Moved to **CI/CD > Editor**](https://gitlab.com/gitlab-org/gitlab/-/issues/263141) in GitLab 13.7. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. +> - It was [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/290117) in GitLab 13.8. +> - It's enabled on GitLab.com. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cicd-configuration-visualization). **(CORE ONLY)** @@ -82,21 +83,21 @@ each job depends only on the previous stage being completed successfully. ### Enable or disable CI/CD configuration visualization **(CORE ONLY)** -CI/CD configuration visualization is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +CI/CD configuration visualization is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can opt to disable it. -To enable it: +To disable it: ```ruby -Feature.enable(:ci_config_visualization_tab) +Feature.disable(:ci_config_visualization_tab) ``` -To disable it: +To enable it: ```ruby -Feature.disable(:ci_config_visualization_tab) +Feature.enable(:ci_config_visualization_tab) ``` ## Commit changes to CI configuration diff --git a/doc/development/agent/identity.md b/doc/development/agent/identity.md index 65de1a6f0c8..884ce015a02 100644 --- a/doc/development/agent/identity.md +++ b/doc/development/agent/identity.md @@ -37,9 +37,9 @@ has a different configuration. Some may enable features A and B, and some may enable features B and C. This flexibility enables different groups of people to use different features of the agent in the same cluster. -For example, [Priyanka (Platform Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#priyanka-platform-engineer) +For example, [Priyanka (Platform Engineer)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#priyanka-platform-engineer) may want to use cluster-wide features of the agent, while -[Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) +[Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#sasha-software-developer) uses the agent that only has access to a particular namespace. Each agent is likely running using a diff --git a/doc/development/packages.md b/doc/development/packages.md index 689dc6b4141..aadd71c9ffa 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -242,6 +242,24 @@ create the package record. Workhorse provides a variety of file metadata such as For testing purposes, you may want to [enable object storage](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/object_storage.md) in your local development environment. +#### Rate Limits on GitLab.com + +Package manager clients can make rapid requests that exceed the +[GitLab.com standard API rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). +This results in a `429 Too Many Requests` error. + +We have opened a set of paths to allow higher rate limits. Unless it is not possible, +new package managers should follow these conventions so they can take advantage of the +expanded package rate limit. + +These route prefixes guarantee a higher rate limit: + +```plaintext +/api/v4/packages/ +/api/v4/projects/:project_id/packages/ +/api/v4/groups/:group_id/-/packages/ +``` + ### Future Work While working on the MVC, contributors might find features that are not mandatory for the MVC but can provide a better user experience. It's generally a good idea to keep an eye on those and open issues. diff --git a/doc/development/usage_ping.md b/doc/development/usage_ping.md index cb38fb9802e..10c3de2f0a1 100644 --- a/doc/development/usage_ping.md +++ b/doc/development/usage_ping.md @@ -132,8 +132,8 @@ general guidelines around how to collect those, due to the individual nature of There are several types of counters which are all found in `usage_data.rb`: - **Ordinary Batch Counters:** Simple count of a given ActiveRecord_Relation -- **Distinct Batch Counters:** Distinct count of a given ActiveRecord_Relation on given column -- **Sum Batch Counters:** Sum the values of a given ActiveRecord_Relation on given column +- **Distinct Batch Counters:** Distinct count of a given ActiveRecord_Relation in a given column +- **Sum Batch Counters:** Sum the values of a given ActiveRecord_Relation in a given column - **Alternative Counters:** Used for settings and configurations - **Redis Counters:** Used for in-memory counts. @@ -153,7 +153,15 @@ For GitLab.com, there are extremely large tables with 15 second query timeouts, | `merge_request_diff_files` | 1082 | | `events` | 514 | -There are two batch counting methods provided, `Ordinary Batch Counters` and `Distinct Batch Counters`. Batch counting requires indexes on columns to calculate max, min, and range queries. In some cases, a specialized index may need to be added on the columns involved in a counter. +We have several batch counting methods available: + +- `Ordinary Batch Counters` +- `Distinct Batch Counters` +- `Sum Batch Counters` +- `Estimated Batch Counters` + +Batch counting requires indexes on columns to calculate max, min, and range queries. In some cases, +you may need to add a specialized index on the columns involved in a counter. ### Ordinary Batch Counters @@ -248,6 +256,82 @@ sum(Issue.group(:state_id), :weight)) # returns => {1=>3542, 2=>6820} ``` +### Estimated Batch Counters + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48233) in GitLab 13.7. + +Estimated batch counter functionality handles `ActiveRecord::StatementInvalid` errors +when used through the provided `estimate_batch_distinct_count` method. +Errors return a value of `-1`. + +WARNING: +This functionality estimates a distinct count of a specific ActiveRecord_Relation in a given column, +which uses the [HyperLogLog](http://algo.inria.fr/flajolet/Publications/FlFuGaMe07.pdf) algorithm. +As the HyperLogLog algorithm is probabilistic, the **results always include error**. +The highest encountered error rate is 4.9%. + +When correctly used, the `estimate_batch_distinct_count` method enables efficient counting over +columns that contain non-unique values, which can not be assured by other counters. + +Method: [`estimate_batch_distinct_count(relation, column = nil, batch_size: nil, start: nil, finish: nil)`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/utils/usage_data.rb#L63) + +The method includes the following arguments: + +- `relation`: The ActiveRecord_Relation to perform the count. +- `column`: The column to perform the distinct count. The default is the primary key. +- `batch_size`: The default is 10,000, from `Gitlab::Database::PostgresHll::BatchDistinctCounter::DEFAULT_BATCH_SIZE`. +- `start`: The custom start of the batch count, to avoid complex minimum calculations. +- `finish`: The custom end of the batch count in order to avoid complex maximum calculations. + +The method includes the following prerequisites: + +1. The supplied `relation` must include the primary key defined as the numeric column. + For example: `id bigint NOT NULL`. +1. The `estimate_batch_distinct_count` can handle a joined relation. To use its ability to + count non-unique columns, the joined relation **must NOT** have a one-to-many relationship, + such as `has_many :boards`. +1. Both `start` and `finish` arguments should always represent primary key relationship values, + even if the estimated count refers to another column, for example: + + ```ruby + estimate_batch_distinct_count(::Note, :author_id, start: ::Note.minimum(:id), finish: ::Note.maximum(:id)) + ``` + +Examples: + +1. Simple execution of estimated batch counter, with only relation provided, + returned value represents estimated number of unique values in `id` column + (which is the primary key) of `Project` relation: + + ```ruby + estimate_batch_distinct_count(::Project) + ``` + +1. Execution of estimated batch counter, where provided relation has applied + additional filter (`.where(time_period)`), number of unique values estimated + in custom column (`:author_id`), and parameters: `start` and `finish` together + apply boundaries that defines range of provided relation to analyze: + + ```ruby + estimate_batch_distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::Note.minimum(:id), finish: ::Note.maximum(:id)) + ``` + +1. Execution of estimated batch counter with joined relation (`joins(:cluster)`), + for a custom column (`'clusters.user_id'`): + + ```ruby + estimate_batch_distinct_count(::Clusters::Applications::CertManager.where(time_period).available.joins(:cluster), 'clusters.user_id') + ``` + +When instrumenting metric with usage of estimated batch counter please add +`_estimated` suffix to its name, for example: + +```ruby + "counts": { + "ci_builds_estimated": estimate_batch_distinct_count(Ci::Build), + ... +``` + ### Redis Counters Handles `::Redis::CommandError` and `Gitlab::UsageDataCounters::BaseCounter::UnknownEvent` @@ -309,6 +393,10 @@ Examples of implementation: #### Redis HLL Counters +WARNING: +HyperLogLog (HLL) is a probabilistic algorithm and its **results always includes some small error**. According to [Redis documentation](https://redis.io/commands/pfcount), data from +used HLL implementation is "approximated with a standard error of 0.81%". + With `Gitlab::UsageDataCounters::HLLRedisCounter` we have available data structures used to count unique values. Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PFCOUNT](https://redis.io/commands/pfcount). @@ -414,7 +502,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF end ``` -1. Track event using `track_usage_event(event_name, values) in services and graphql +1. Track event using `track_usage_event(event_name, values) in services and GraphQL Increment unique values count using Redis HLL, for given event name. @@ -422,7 +510,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF [Track usage event for incident created in service](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/issues/update_service.rb) - [Track usage event for incident created in graphql](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/alert_management/update_alert_status.rb) + [Track usage event for incident created in GraphQL](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/alert_management/update_alert_status.rb) ```ruby track_usage_event(:incident_management_incident_created, current_user.id) @@ -549,7 +637,7 @@ For each event we add metrics for the weekly and monthly time frames, and totals - `#{event_name}_weekly`: Data for 7 days for daily [aggregation](#adding-new-events) events and data for the last complete week for weekly [aggregation](#adding-new-events) events. - `#{event_name}_monthly`: Data for 28 days for daily [aggregation](#adding-new-events) events and data for the last 4 complete weeks for weekly [aggregation](#adding-new-events) events. -Redis HLL implementation calculates automatic total metrics, if there are more than one metric for the same category, aggregation and Redis slot. +Redis HLL implementation calculates automatic total metrics, if there are more than one metric for the same category, aggregation and Redis slot. - `#{category}_total_unique_counts_weekly`: Total unique counts for events in the same category for the last 7 days or the last complete week, if events are in the same Redis slot and we have more than one metric. - `#{category}_total_unique_counts_monthly`: Total unique counts for events in same category for the last 28 days or the last 4 complete weeks, if events are in the same Redis slot and we have more than one metric. @@ -732,7 +820,7 @@ On GitLab.com, we have DangerBot setup to monitor Product Intelligence related f ### 10. Verify your metric -On GitLab.com, the Product Intelligence team regularly monitors Usage Ping. They may alert you that your metrics need further optimization to run quicker and with greater success. You may also use the [Usage Ping QA dashboard](https://app.periscopedata.com/app/gitlab/632033/Usage-Ping-QA) to check how well your metric performs. The dashboard allows filtering by GitLab version, by "Self-managed" & "Saas" and shows you how many failures have occurred for each metric. Whenever you notice a high failure rate, you may re-optimize your metric. +On GitLab.com, the Product Intelligence team regularly monitors Usage Ping. They may alert you that your metrics need further optimization to run quicker and with greater success. You may also use the [Usage Ping QA dashboard](https://app.periscopedata.com/app/gitlab/632033/Usage-Ping-QA) to check how well your metric performs. The dashboard allows filtering by GitLab version, by "Self-managed" & "SaaS" and shows you how many failures have occurred for each metric. Whenever you notice a high failure rate, you may re-optimize your metric. ### Optional: Test Prometheus based Usage Ping @@ -783,8 +871,6 @@ appear to be associated to any of the services running, since they all appear to ## Aggregated metrics > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45979) in GitLab 13.6. -> - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. -> - It's enabled on GitLab.com. WARNING: This feature is intended solely for internal GitLab use. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index a06c7a8f325..65d3129a825 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -88,6 +88,22 @@ similar to how they appear when viewing a [milestone](../../project/milestones/i Burndown charts help track completion progress of total scope, and burnup charts track the daily total count and weight of issues added to and completed in a given timebox. +### Group issues by label + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225500) in GitLab 13.8. + +You can group the list of issues by label. +This can help you view issues that have your team's label, +and get a more accurate understanding of scope attributable to each label. + +To group issues by label: + +1. In the **Group by** dropdown, select **Label**. +1. Select the **Filter by label** dropdown. +1. Select the labels you want to group by in the labels dropdown. + You can also search for labels by typing in the search input. +1. Click or tap outside of the label dropdown. The page is now grouped by the selected labels. + ## Disable iterations **(STARTER ONLY)** GitLab Iterations feature is deployed with a feature flag that is **enabled by default**. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index fbede6d13b7..5e5aadfae2b 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -141,11 +141,10 @@ You can use the Dependency Proxy to pull your base image. bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= ``` - This can also be other credentials such as: + This can also be a [personal access token](../../../user/profile/personal_access_tokens.md) such as: ```shell echo -n "my_username:personal_access_token" | base64 - echo -n "deploy_token_username:deploy_token" | base64 ``` 1. Create a [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 50837e69e74..35172663cc1 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -123,7 +123,7 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/proje To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`: ```shell -nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<your_group_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> +nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> ``` - `<source_name>` is the desired source name. @@ -131,7 +131,7 @@ nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/ For example: ```shell -nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/groups/23/packages/nuget/index.json" -UserName carol -Password 12345678asdf +nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" -UserName carol -Password 12345678asdf ``` ### Add a source with Visual Studio @@ -173,7 +173,7 @@ To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endp 1. Select **Add**. 1. Complete the following fields: - **Name**: Name for the source. - - **Location**: `https://gitlab.example.com/api/v4/group/<your_group_id>/packages/nuget/index.json`, + - **Location**: `https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json`, where `<your_group_id>` is your group ID, and `gitlab.example.com` is your domain name. - **Username**: Your GitLab username or deploy token username. @@ -227,7 +227,7 @@ To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Re <configuration> <packageSources> <clear /> - <add key="gitlab" value="https://gitlab.example.com/api/v4/group/<your_group_id>/packages/nuget/index.json" /> + <add key="gitlab" value="https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" /> </packageSources> <packageSourceCredentials> <gitlab> diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index ad18e5e78fd..38ef01b7537 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -153,8 +153,7 @@ Users are notified of the following events: | Project access level changed | User | Sent when user project access level is changed | | User added to group | User | Sent when user is added to group | | Group access level changed | User | Sent when user group access level is changed | -| Personal Access Tokens expiring soon | User | Security email, always sent. | -<!-- Do not delete or lint this instance of future tense --> +| Personal Access Tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User | Security email, always sent. | | Personal Access Tokens have expired | User | Security email, always sent. | | Project moved | Project members (1) | (1) not disabled | | New release | Project members | Custom notification | diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index c01efd9c813..64be3182dab 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -13,6 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > quick actions when updating the description of issues, epics, and merge requests. > - Introduced in [GitLab 13.8](https://gitlab.com/gitlab-org/gitlab/-/issues/292393): when you enter > `/` into a description or comment field, all available quick actions are displayed in a scrollable list. +> - The rebase quick action was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49800) in GitLab 13.8. Quick actions are textual shortcuts for common actions on issues, epics, merge requests, and commits that are usually done by clicking buttons or dropdowns in the GitLab UI. @@ -61,7 +62,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/promote` | ✓ | | | Promote issue to epic. **(PREMIUM)** | | `/publish` | ✓ | | | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) **(ULTIMATE)** | | `/reassign @user1 @user2` | ✓ | ✓ | | Replace current assignees with those specified. **(STARTER)** | -| `/rebase` | | ✓ | | Rebase source branch. This will schedule a background task that attempt to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` will be ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. | +| `/rebase` | | ✓ | | Rebase source branch. This will schedule a background task that attempt to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` will be ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab will display a message that a rebase cannot be scheduled. Rebase failures will be displayed with the merge request status. | | `/reassign_reviewer @user1 @user2` | | ✓ | | Replace current reviewers with those specified. **(STARTER)** | | `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace current labels with those specified. | | `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 29b24028e48..af8e78afb28 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -33,8 +33,8 @@ start seeing results. ## Command palette You can see all available commands for manipulating editor content by pressing -the <kbd>F1</kbd> key when the editor is in focus. After that, -you'll see a complete list of available commands for +the <kbd>F1</kbd> key when the editor is in focus. After that, the editor displays +a complete list of available commands for manipulating editor content. The editor supports commands for multi-cursor editing, code block folding, commenting, searching and replacing, navigating editor warnings and suggestions, and more. @@ -47,7 +47,7 @@ the command without having to select it in the command palette. ## Syntax highlighting -As expected from an IDE, syntax highlighting for many languages within +As expected from an IDE, syntax highlighting for many languages in the Web IDE makes your direct editing even easier. The Web IDE currently provides: @@ -78,7 +78,7 @@ All the themes GitLab supports for syntax highlighting are added to the Web IDE' You can pick a theme from your [profile preferences](../../profile/preferences.md). The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and -the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), +the [Solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), which apply to the entire Web IDE screen. | Solarized Light Theme | Solarized Dark Theme | Dark Theme | @@ -144,12 +144,13 @@ schemas: Each schema entry supports two properties: -- `uri`: please provide an absolute URL for the schema definition file here. The schema from this URL -is loaded when a matching file is open. -- `match`: a list of matching paths or glob expressions. If a schema matches a particular path pattern, -it will be applied to that file. Please enclose the pattern in quotes if it begins with an asterisk (`*`), -it's be applied to that file. If a pattern begins with an asterisk (`*`), enclose it in quotation -marks. Otherwise, the configuration file is not valid YAML. +- `uri`: please provide an absolute URL for the schema definition file here. + The schema from this URL is loaded when a matching file is open. +- `match`: a list of matching paths or glob expressions. If a schema matches a + particular path pattern, it is applied to that file. Please enclose the pattern + in quotes if it begins with an asterisk (`*`), it's be applied to that file. + If a pattern begins with an asterisk (`*`), enclose it in quotation marks. + Otherwise, the configuration file is not valid YAML. ## Configure the Web IDE @@ -180,7 +181,7 @@ The Web IDE currently supports the following `.editorconfig` settings: After making your changes, click the **Commit** button on the bottom-left to review the list of changed files. -Once you have finalized your changes, you can add a commit message, commit the +After you have finalized your changes, you can add a commit message, commit the changes and directly create a merge request. In case you don't have write access to the selected branch, you see a warning, but can still create a new branch and start a merge request. @@ -268,7 +269,7 @@ GitLab.com ![Administrator Live Preview setting](img/admin_live_preview_v13_0.png) -Once you have done that, you can preview projects with a `package.json` file and +After you have done that, you can preview projects with a `package.json` file and a `main` entry point inside the Web IDE. An example `package.json` is shown below. @@ -325,7 +326,7 @@ In order to enable the Web IDE terminals you need to create the file file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md) syntax but with some restrictions: -- No global blocks can be defined (i.e., `before_script` or `after_script`) +- No global blocks (such as `before_script` or `after_script`) can be defined. - Only one job named `terminal` can be added to this file. - Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and `variables` are allowed to be used to configure the job. @@ -350,7 +351,7 @@ terminal: NODE_ENV: "test" ``` -Once the terminal has started, the console is displayed and we could access +After the terminal has started, the console is displayed and we could access the project repository files. **Important**. The terminal job is branch dependent. This means that the @@ -364,7 +365,7 @@ If there is no configuration file in a branch, an error message is shown. If Interactive Terminals are available for the current user, the **Terminal** button is visible in the right sidebar of the Web IDE. Click this button to open or close the terminal tab. -Once open, the tab shows the **Start Web Terminal** button. This button may +After opening, the tab shows the **Start Web Terminal** button. This button may be disabled if the environment is not configured correctly. If so, a status message describes the issue. Here are some reasons why **Start Web Terminal** may be disabled: @@ -378,7 +379,7 @@ can be closed and reopened and the state of the terminal is not affected. When the terminal is started and is successfully connected to the runner, then the runner's shell prompt appears in the terminal. From here, you can enter -commands executed within the runner's environment. This is similar +commands executed in the runner's environment. This is similar to running commands in a local terminal or through SSH. While the terminal is running, it can be stopped by clicking **Stop Terminal**. @@ -426,7 +427,7 @@ terminal: [predefined environment variable](../../../ci/variables/predefined_variables.md) for GitLab Runners. This is where your project's repository resides. -Once you have configured the web terminal for file syncing, then when the web +After you have configured the web terminal for file syncing, then when the web terminal is started, a **Terminal** status is visible in the status bar. ![Web IDE Client Side Evaluation](img/terminal_status.png) @@ -434,7 +435,7 @@ terminal is started, a **Terminal** status is visible in the status bar. Changes made to your files via the Web IDE sync to the running terminal when: -- <kbd>Ctrl</kbd> + <kbd>S</kbd> (or <kbd>Cmd</kbd> + <kbd>S</kbd> on Mac) +- <kbd>Control</kbd> + <kbd>S</kbd> (or <kbd>Command</kbd> + <kbd>S</kbd> on Mac) is pressed while editing a file. - Anything outside the file editor is clicked after editing a file. - A file or folder is created, deleted, or renamed. @@ -446,7 +447,7 @@ The Web IDE has a few limitations: - Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, please note that the user is limited to having only one active terminal at a time. -- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository will be overwritten with the modified LFS file content. +- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository is overwritten with the modified LFS file content. ### Troubleshooting diff --git a/doc/user/search/index.md b/doc/user/search/index.md index b6be21e9653..d229c27b608 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -18,7 +18,7 @@ The number displayed on their right represents the number of issues and merge re ![issues and MRs dashboard links](img/dashboard_links.png) -When you click **Issues**, you'll see the opened issues assigned to you straight away: +When you click **Issues**, the opened issues assigned to you are shown straight away: ![Issues assigned to you](img/issues_assigned_to_you.png) @@ -29,7 +29,7 @@ You can also filter the results using the search and filter field, as described ### Issues and MRs assigned to you or created by you -You'll also find shortcuts to issues and merge requests created by you or assigned to you +GitLab shows shortcuts to issues and merge requests created by you or assigned to you on the search field on the top-right of your screen: ![shortcut to your issues and merge requests](img/issues_mrs_shortcut.png) @@ -40,7 +40,7 @@ on the search field on the top-right of your screen: > - Filtering by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. > - Filtering by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. -Follow these steps to filter the **Issues** and **Merge Requests** list pages within projects and +Follow these steps to filter the **Issues** and **Merge Requests** list pages in projects and groups: 1. Click in the field **Search or filter results...**. @@ -74,7 +74,7 @@ Some filter fields like milestone and assignee, allow you to filter by **None** ![filter by none any](img/issues_filter_none_any.png) -Selecting **None** returns results that have an empty value for that field. E.g.: no milestone, no assignee. +Selecting **None** returns results that have an empty value for that field. For example: no milestone, no assignee. Selecting **Any** does the opposite. It returns results that have a non-empty value for that field. @@ -83,11 +83,11 @@ Selecting **Any** does the opposite. It returns results that have a non-empty va You can filter issues and merge requests by specific terms included in titles or descriptions. - Syntax - - Searches look for all the words in a query, in any order. E.g.: searching - issues for `display bug` will return all issues matching both those words, in any order. + - Searches look for all the words in a query, in any order. For example: searching + issues for `display bug` returns all issues matching both those words, in any order. - To find the exact term, use double quotes: `"display bug"` - Limitation - - For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching + - For performance reasons, terms shorter than 3 chars are ignored. For example: searching issues for `included in titles` is same as `included titles` - Search is limited to 4096 characters and 64 terms per query. @@ -157,7 +157,7 @@ relevant users or other attributes. For performance optimization, there is a requirement of a minimum of three characters to begin your search. For example, if you want to search for -issues that have the assignee "Simone Presley", you'll need to type at +issues that have the assignee "Simone Presley", you must type at least "Sim" before autocomplete gives any relevant results. ## Search history @@ -170,11 +170,11 @@ You can view recent searches by clicking on the little arrow-clock icon, which i Individual filters can be removed by clicking on the filter's (x) button or backspacing. The entire search filter can be cleared by clicking on the search box's (x) button or via <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd>. -To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>⌫</kbd> keyboard combination can be used. +To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> keyboard combination can be used. ## Filtering with multiple filters of the same type -Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results will only include entries whereby the assignees are assigned to both Sam and Sarah are returned. +Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned. ![multiple assignees filtering](img/multiple_assignees.png) @@ -190,7 +190,7 @@ author, type, and action. Also, you can sort them by You can search through your projects from the left menu, by clicking the menu bar, then **Projects**. On the field **Filter by name**, type the project or group name you want to find, and GitLab -will filter them for you as you type. +filters them for you as you type. You can also look for the projects you [starred](../project/index.md#star-a-project) (**Starred projects**), and **Explore** all public and internal projects available in GitLab.com, from which you can filter by visibility, @@ -207,7 +207,7 @@ Similarly to [projects search](#projects), you can search through your groups fr the left menu, by clicking the menu bar, then **Groups**. On the field **Filter by name**, type the group name you want to find, and GitLab -will filter them for you as you type. +filters them for you as you type. You can also **Explore** all public and internal groups available in GitLab.com, and sort them by **Last created**, **Oldest created**, **Last updated**, or **Oldest updated**. @@ -219,15 +219,15 @@ You can also filter them by name (issue title), from the field **Filter by name* When you want to search for issues to add to lists present in your Issue Board, click the button **Add issues** on the top-right of your screen, opening a modal window from which -you'll be able to, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, +you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, and **Labels**, select multiple issues to add to a list of your choice: ![search and select issues to add to board](img/search_issues_board.png) ## Shortcut -You'll find a shortcut on the search field on the top-right of the project's dashboard to -quickly access issues and merge requests created or assigned to you within that project: +GitLab shows a shortcut on the search field on the top-right of the project's dashboard to +quickly access issues and merge requests created or assigned to you in that project: ![search per project - shortcut](img/project_search.png) @@ -242,12 +242,12 @@ You can also type in this search bar to see autocomplete suggestions for: - Recently viewed issues (try and type some word from the title of a recently viewed issue) - Recently viewed merge requests (try and type some word from the title of a recently viewed merge request) - Recently viewed epics (try and type some word from the title of a recently viewed epic) -- [GitLab Flavored Markdown](../markdown.md#special-gitlab-references) (GFM) for issues within a project (try and type a GFM reference for an issue) +- [GitLab Flavored Markdown](../markdown.md#special-gitlab-references) (GFM) for issues in a project (try and type a GFM reference for an issue) ## Basic search The Basic search in GitLab is a global search service that allows you to search -across the entire GitLab instance, within a group, or a single project. Basic search is +across the entire GitLab instance, in a group, or in a single project. Basic search is backed by the database and allows searching in: - Projects @@ -262,12 +262,12 @@ backed by the database and allows searching in: - Wiki (Project only) To start a search, type into the search bar on the top-right of the screen. You can always search -in all GitLab and may also see the options to search within a group or project if you are in the +in all GitLab and may also see the options to search in a group or project if you are in the group or project dashboard. ![basic search](img/basic_search.png) -Once the results are returned, you can modify the search, select a different type of data to +After the results are returned, you can modify the search, select a different type of data to search, or choose a specific group or project. ![basic_search_results](img/basic_search_results.png) @@ -282,11 +282,11 @@ the search field on the top-right of your screen while the project page is open. ### SHA search -You can quickly access a commit from within the project dashboard by entering the SHA -into the search field on the top right of the screen. If a single result is found, you will be +You can quickly access a commit from the project dashboard by entering the SHA +into the search field on the top right of the screen. If a single result is found, you are redirected to the commit result and given the option to return to the search results page. -![project sha search redirect](img/project_search_sha_redirect.png) +![project SHA search redirect](img/project_search_sha_redirect.png) ## Advanced Search **(STARTER)** @@ -314,7 +314,7 @@ This feature might not be available to you. Check the **version history** note a You can search inside the project’s settings sections by entering a search term in the search box located at the top of the page. The search results -will appear highlighted in the sections that match the search term. +appear highlighted in the sections that match the search term. ![Search project settings](img/project_search_general_settings_v13_8.png) diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 5dd93f9e9db..af499221da6 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -69,8 +69,8 @@ new commit to the master branch is recorded. Commit messages are automatically generated. The snippet's repository has only one branch (master) by default, deleting it or creating other branches is not supported. -Existing snippets will be automatically migrated in 13.0. Their current -content will be saved as the initial commit to the snippets' repository. +Existing snippets are automatically migrated in 13.0. Their current +content is saved as the initial commit to the snippets' repository. ### Filenames @@ -86,10 +86,10 @@ number increases incrementally when more snippets without an attributed filename are added. When upgrading from an earlier version of GitLab to 13.0, existing snippets -without a supported filename will be renamed to a compatible format. For -example, if the snippet's filename is `http://a-weird-filename.me` it will -be changed to `http-a-weird-filename-me` to be included in the snippet's -repository. As snippets are stored by ID, changing their filenames will not break +without a supported filename are renamed to a compatible format. For +example, if the snippet's filename is `http://a-weird-filename.me` it is +changed to `http-a-weird-filename-me` to be included in the snippet's +repository. As snippets are stored by ID, changing their filenames breaks direct or embedded links to the snippet. ### Multiple files by Snippet @@ -105,8 +105,8 @@ to a certain context. For example: - A snippet with a `docker-compose.yml` file and its associated `.env` file. - A `gulpfile.js` file coupled with a `package.json` file, which together can be used to bootstrap a project and manage its dependencies. -Snippets support between 1 and 10 files. They can be managed via Git (since they're [versioned](#versioned-snippets) -by a Git repository), through the [Snippets API](../api/snippets.md), or within the GitLab UI. +Snippets support between 1 and 10 files. They can be managed via Git (because they're [versioned](#versioned-snippets) +by a Git repository), through the [Snippets API](../api/snippets.md), or in the GitLab UI. ![Multi-file Snippet](img/gitlab_snippet_v13_5.png) @@ -139,7 +139,7 @@ master branch. ### Reduce snippets repository size -Since versioned Snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md), +Because versioned Snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md), it's recommended to keep snippets' repositories as compact as possible. For more information about tools to compact repositories, @@ -151,7 +151,7 @@ see the documentation on [reducing repository size](../user/project/repository/r - Creating or deleting branches is not supported. Only a default *master* branch is used. - Git tags are not supported in snippet repositories. - Snippets' repositories are limited to 10 files. Attempting to push more -than 10 files will result in an error. +than 10 files results in an error. - Revisions are not *yet* visible to the user on the GitLab UI, but it's planned to be added in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) for updates. @@ -187,9 +187,9 @@ facilitating the collaboration among users. You can download the raw content of a snippet. -By default snippets will be downloaded with Linux-style line endings (`LF`). If +By default snippets are downloaded with Linux-style line endings (`LF`). If you want to preserve the original line endings you need to add a parameter `line_ending=raw` -(e.g., `https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw`). In case a +(For example: `https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw`). In case a snippet was created using the GitLab web interface the original line ending is Windows-like (`CRLF`). ## Embedded snippets @@ -207,7 +207,7 @@ To embed a snippet, first make sure that: - In **Project > Settings > Permissions**, the snippets permissions are set to **Everyone with access** -Once the above conditions are met, the "Embed" section will appear in your +After the above conditions are met, the "Embed" section appears in your snippet where you can simply click on the "Copy" button. This copies a one-line script that you can add to any website or blog post. |