diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-16 18:25:58 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-16 18:25:58 +0000 |
| commit | a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 (patch) | |
| tree | fb69158581673816a8cd895f9d352dcb3c678b1e /doc/development | |
| parent | d16b2e8639e99961de6ddc93909f3bb5c1445ba1 (diff) | |
| download | gitlab-ce-a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4.tar.gz | |
Add latest changes from gitlab-org/gitlab@14-0-stable-eev14.0.0-rc42
Diffstat (limited to 'doc/development')
138 files changed, 3414 insertions, 2285 deletions
diff --git a/doc/development/README.md b/doc/development/README.md index 37d8a8fa570..bc996fdff21 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -61,11 +61,11 @@ GitLab instance, see the [administration documentation](../administration/index. Complementary reads: -- [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/blob/master/PROCESS.md) +- [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md) - [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer) - [Guidelines for implementing Enterprise Edition features](ee_features.md) - [Danger bot](dangerbot.md) -- [Generate a changelog entry with `bin/changelog`](changelog.md) +- [Guidelines for changelogs](changelog.md) - [Requesting access to ChatOps on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLab team members) - [Patch release process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/patch/process.md#process-for-developers) - [Adding a new service component to GitLab](adding_service_component.md) diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index e8b71e0509a..4d521d11a69 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -16,7 +16,7 @@ We use the [GraphQL Ruby gem](https://graphql-ruby.org/) written by [Robert Moso In addition, we have a subscription to [GraphQL Pro](https://graphql.pro/). For details see [GraphQL Pro subscription](graphql_guide/graphql_pro.md). All GraphQL queries are directed to a single endpoint -([`app/controllers/graphql_controller.rb#execute`](https://gitlab.com/gitlab-org/gitlab/blob/master/app%2Fcontrollers%2Fgraphql_controller.rb)), +([`app/controllers/graphql_controller.rb#execute`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app%2Fcontrollers%2Fgraphql_controller.rb)), which is exposed as an API endpoint at `/api/graphql`. ## Deep Dive @@ -862,7 +862,7 @@ overhead. If you are writing: Resolvers may raise errors, which will be converted to top-level errors as appropriate. All anticipated errors should be caught and transformed to an appropriate GraphQL error (see -[`Gitlab::Graphql::Errors`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/graphql/errors.rb)). +[`Gitlab::Graphql::Errors`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/graphql/errors.rb)). Any uncaught errors will be suppressed and the client will receive the message `Internal service error`. @@ -1575,6 +1575,41 @@ deprecated aliased mutations. EE mutations should follow the same process. For an example of the merge request process, read [merge request !42588](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42588). +## Subscriptions + +We use subscriptions to push updates to clients. We use the [Action Cable implementation](https://graphql-ruby.org/subscriptions/action_cable_implementation) +to deliver the messages over websockets. + +When a client subscribes to a subscription, we store their query in-memory within Puma workers. Then when the subscription is triggered, +the Puma workers execute the stored GraphQL queries and push the results to the clients. + +NOTE: +We cannot test subscriptions using GraphiQL, because they require an Action Cable client, which GraphiQL does not support at the moment. + +### Building subscriptions + +All fields under `Types::SubscriptionType` are subscriptions that clients can subscribe to. These fields require a subscription class, +which is a descendant of `Subscriptions::BaseSubscription` and is stored under `app/graphql/subscriptions`. + +The arguments required to subscribe and the fields that are returned are defined within the subscription class. Multiple fields can share +the same subscription class if they have the same arguments and return the same fields. + +This class runs during the initial subscription request and subsequent updates. You can read more about this in the +[GraphQL Ruby guides](https://graphql-ruby.org/subscriptions/subscription_classes). + +### Authorization + +You should implement the `#authorized?` method of the subscription class so that the initial subscription and subsequent updates are authorized. + +When a user is not authorized, you should call the `unauthorized!` helper so that execution is halted and the user is unsubscribed. Returning `false` +results in redaction of the response but we leak information that some updates are happening. This is due to a +[bug in the GraphQL gem](https://github.com/rmosolgo/graphql-ruby/issues/3390). + +### Triggering subscriptions + +Define a method under the `GraphqlTriggers` module to trigger a subscription. Do not call `GitlabSchema.subscriptions.trigger` directly in application +code so that we have a single source of truth and we do not trigger a subscription with different arguments and objects. + ## Pagination implementation To learn more, visit [GraphQL pagination](graphql_guide/pagination.md). @@ -1614,7 +1649,7 @@ is merged. ### `Types::TimeType` -[`Types::TimeType`](https://gitlab.com/gitlab-org/gitlab/blob/master/app%2Fgraphql%2Ftypes%2Ftime_type.rb) +[`Types::TimeType`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app%2Fgraphql%2Ftypes%2Ftime_type.rb) must be used as the type for all fields and arguments that deal with Ruby `Time` and `DateTime` objects. diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index dd43281da6d..c16e86726a8 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -15,7 +15,7 @@ to access them as we do in Rails views), local variables are fine. ## Entities -Always use an [Entity](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/entities) to present the endpoint's payload. +Always use an [Entity](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/entities) to present the endpoint's payload. ## Documentation @@ -28,7 +28,7 @@ See the [Documentation Style Guide RESTful API page](documentation/restful_api_s ## Methods and parameters description Every method must be described using the [Grape DSL](https://github.com/ruby-grape/grape#describing-methods) -(see [`environments.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/environments.rb) +(see [`environments.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/environments.rb) for a good example): - `desc` for the method summary. You should pass it a block for additional @@ -252,7 +252,7 @@ A standard way to do this within the API is for models to implement a scope called `with_api_entity_associations` that preloads the associations and data returned in the API. An example of this scope can be seen in -[the `Issue` model](https://gitlab.com/gitlab-org/gitlab/blob/2fedc47b97837ea08c3016cf2fb773a0300a4a25/app%2Fmodels%2Fissue.rb#L62). +[the `Issue` model](https://gitlab.com/gitlab-org/gitlab/-/blob/2fedc47b97837ea08c3016cf2fb773a0300a4a25/app%2Fmodels%2Fissue.rb#L62). In situations where the same model has multiple entities in the API (for instance, `UserBasic`, `User` and `UserPublic`) you should use your @@ -260,7 +260,7 @@ discretion with applying this scope. It may be that you optimize for the most basic entity, with successive entities building upon that scope. The `with_api_entity_associations` scope also [automatically preloads -data](https://gitlab.com/gitlab-org/gitlab/blob/19f74903240e209736c7668132e6a5a735954e7c/app%2Fmodels%2Ftodo.rb#L34) +data](https://gitlab.com/gitlab-org/gitlab/-/blob/19f74903240e209736c7668132e6a5a735954e7c/app%2Fmodels%2Ftodo.rb#L34) for `Todo` _targets_ when returned in the [to-dos API](../api/todos.md). For more context and discussion about preloading see diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md index 3c1c91e0d2e..b532a7ff98b 100644 --- a/doc/development/application_limits.md +++ b/doc/development/application_limits.md @@ -94,7 +94,7 @@ project.actual_limits.exceeded?(:project_hooks, 10) #### `Limitable` concern -The [`Limitable` concern](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/limitable.rb) +The [`Limitable` concern](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/concerns/limitable.rb) can be used to validate that a model does not exceed the limits. It ensures that the count of the records for the current model does not exceed the defined limit. diff --git a/doc/development/appsec/index.md b/doc/development/appsec/index.md index e8ce885e75d..2ece3fdf4bf 100644 --- a/doc/development/appsec/index.md +++ b/doc/development/appsec/index.md @@ -20,7 +20,7 @@ the feature categories in the [Secure](https://about.gitlab.com/stages-devops-li - `AppSec::ContainerScanning`: Container Scanning code. - `AppSec::Dast`: DAST code. - `AppSec::DependencyScanning`: Dependency Scanning code. - - `AppSec::Fuzzing::Api`: API Fuzzing code. + - `AppSec::Fuzzing::API`: API Fuzzing code. - `AppSec::Fuzzing::Coverage`: Coverage Fuzzing code. - `AppSec::Fuzzing`: Shared fuzzing code. - `AppSec::LicenseCompliance`: License Compliance code. diff --git a/doc/development/architecture.md b/doc/development/architecture.md index fdcaa91a639..9801b24fdd0 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -15,14 +15,14 @@ There are two software distributions of GitLab: GitLab is available under [different subscriptions](https://about.gitlab.com/pricing/). -New versions of GitLab are released from stable branches, and the `master` branch is used for +New versions of GitLab are released from stable branches, and the `main` branch is used for bleeding-edge development. For more information, visit the [GitLab Release Process](https://about.gitlab.com/handbook/engineering/releases/). Both distributions require additional components. These components are described in the [Component details](#components) section, and all have their own repositories. -New versions of each dependent component are usually tags, but staying on the `master` branch of the +New versions of each dependent component are usually tags, but staying on the `main` branch of the GitLab codebase gives you the latest stable version of those components. New versions are generally released around the same time as GitLab releases, with the exception of informal security updates deemed critical. @@ -46,14 +46,14 @@ and pre-compiled assets. The GitLab application uses PostgreSQL for persistent database information (for example, users, permissions, issues, or other metadata). GitLab stores the bare Git repositories in the location -defined in [the configuration file, `repositories:` section](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example). +defined in [the configuration file, `repositories:` section](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example). It also keeps default branch and hook information with the bare repository. When serving repositories over HTTP/HTTPS GitLab uses the GitLab API to resolve authorization and access and to serve Git objects. The add-on component GitLab Shell serves repositories over SSH. It manages the SSH keys within the -location defined in [the configuration file, `GitLab Shell` section](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example). +location defined in [the configuration file, `GitLab Shell` section](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example). The file in that location should never be manually edited. GitLab Shell accesses the bare repositories through Gitaly to serve Git objects, and communicates with Redis to submit jobs to Sidekiq for GitLab to process. GitLab Shell queries the GitLab API to determine authorization and access. @@ -215,7 +215,7 @@ click NodeExporter "./architecture.html#node-exporter" ### Component legend - ✅ - Installed by default -- ⚙ - Requires additional configuration, or GitLab Managed Apps +- ⚙ - Requires additional configuration - ⤓ - Manual installation required - ❌ - Not supported or no instructions available - N/A - Not applicable @@ -234,7 +234,6 @@ Component statuses are linked to configuration documentation for each component. | [GitLab Exporter](#gitlab-exporter) | Generates a variety of GitLab metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | | [GitLab Geo Node](#gitlab-geo) | Geographically distributed GitLab nodes | ⚙ | ⚙ | ❌ | ❌ | ✅ | ❌ | ⚙ | EE Only | | [GitLab Kubernetes Agent](#gitlab-kubernetes-agent) | Integrate Kubernetes clusters in a cloud-native way | ⚙ | ⚙ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | EE Only | -| [GitLab Managed Apps](#gitlab-managed-apps) | Deploy Helm, Ingress, Cert-Manager, Prometheus, GitLab Runner, JupyterHub, or Knative to a cluster | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | | [GitLab Pages](#gitlab-pages) | Hosts static websites | ⚙ | ⚙ | ❌ | ❌ | ✅ | ⚙ | ⚙ | CE & EE | | [GitLab Kubernetes Agent](#gitlab-kubernetes-agent) | Integrate Kubernetes clusters in a cloud-native way | ⚙ | ⚙ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | EE Only | | [GitLab self-monitoring: Alertmanager](#alertmanager) | Deduplicates, groups, and routes alerts from Prometheus | ⚙ | ⚙ | ✅ | ⚙ | ✅ | ❌ | ❌ | CE & EE | @@ -435,7 +434,7 @@ GitLab CI/CD is the open-source continuous integration service included with Git - [Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template) - [Charts](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/) - [Source](../install/installation.md#install-gitlab-shell) - - [GDK](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) + - [GDK](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) - Layer: Core Service (Processor) - GitLab.com: [Service Architecture](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/#service-architecture) @@ -668,8 +667,8 @@ An external registry can also be configured to use GitLab as an auth endpoint. - Configuration: - [Omnibus](https://docs.gitlab.com/omnibus/settings/configuration.html#error-reporting-and-logging-with-sentry) - [Charts](https://docs.gitlab.com/charts/charts/globals#sentry-settings) - - [Source](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) - - [GDK](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) + - [Source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) + - [GDK](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) - Layer: Monitoring - GitLab.com: [Searching Sentry](https://about.gitlab.com/handbook/support/workflows/500_errors.html#searching-sentry) @@ -685,8 +684,8 @@ For monitoring deployed apps, see the [Sentry integration docs](../operations/er - [Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template) - [Charts](https://docs.gitlab.com/charts/charts/gitlab/sidekiq/) - [Minikube Minimal](https://docs.gitlab.com/charts/charts/gitlab/sidekiq/index.html) - - [Source](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) - - [GDK](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) + - [Source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) + - [GDK](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) - Layer: Core Service (Processor) - Process: `sidekiq` - GitLab.com: [Sidekiq](../user/gitlab_com/index.md#sidekiq) @@ -695,44 +694,26 @@ Sidekiq is a Ruby background job processor that pulls jobs from the Redis queue #### Puma -Starting with GitLab 13.0, Puma is the default web server and Unicorn has been -disabled by default. +Starting with GitLab 13.0, Puma is the default web server. -- [Project page](https://gitlab.com/gitlab-org/gitlab/blob/master/README.md) +- [Project page](https://gitlab.com/gitlab-org/gitlab/-/blob/master/README.md) - Configuration: - [Omnibus](https://docs.gitlab.com/omnibus/settings/puma.html) - [Charts](https://docs.gitlab.com/charts/charts/gitlab/webservice/) - [Source](../install/installation.md#configure-it) - - [GDK](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) + - [GDK](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) - Layer: Core Service (Processor) - Process: `puma` - GitLab.com: [Puma](../user/gitlab_com/index.md#puma) [Puma](https://puma.io/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often this displays in process output as `bundle` or `config.ru` depending on the GitLab version. -#### Unicorn - -Starting with GitLab 13.0, Puma is the default web server and Unicorn has been -disabled by default. - -- [Project page](https://gitlab.com/gitlab-org/gitlab/blob/master/README.md) -- Configuration: - - [Omnibus](https://docs.gitlab.com/omnibus/settings/unicorn.html) - - [Charts](https://docs.gitlab.com/charts/charts/gitlab/webservice/) - - [Source](../install/installation.md#configure-it) - - [GDK](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) -- Layer: Core Service (Processor) -- Process: `unicorn` -- GitLab.com: [Unicorn](../user/gitlab_com/index.md#unicorn) - -[Unicorn](https://yhbt.net/unicorn/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often this displays in process output as `bundle` or `config.ru` depending on the GitLab version. - #### LDAP Authentication - Configuration: - [Omnibus](../administration/auth/ldap/index.md) - [Charts](https://docs.gitlab.com/charts/charts/globals.html#ldap) - - [Source](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) + - [Source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/ldap.md) - Layer: Core Service (Processor) - GitLab.com: [Product Tiers](https://about.gitlab.com/pricing/#gitlab-com) @@ -742,8 +723,8 @@ disabled by default. - Configuration: - [Omnibus](https://docs.gitlab.com/omnibus/settings/smtp.html) - [Charts](https://docs.gitlab.com/charts/installation/command-line-options.html#outgoing-email-configuration) - - [Source](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) - - [GDK](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) + - [Source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) + - [GDK](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) - Layer: Core Service (Processor) - GitLab.com: [Mail configuration](../user/gitlab_com/index.md#mail-configuration) @@ -752,33 +733,11 @@ disabled by default. - Configuration: - [Omnibus](../administration/incoming_email.md) - [Charts](https://docs.gitlab.com/charts/installation/command-line-options.html#incoming-email-configuration) - - [Source](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) - - [GDK](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) + - [Source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) + - [GDK](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) - Layer: Core Service (Processor) - GitLab.com: [Mail configuration](../user/gitlab_com/index.md#mail-configuration) -#### GitLab Managed Apps - -- Configuration: - - [Omnibus](../user/project/clusters/index.md#installing-applications) - - [Charts](../user/project/clusters/index.md#installing-applications) - - [Source](../user/project/clusters/index.md#installing-applications) - - [GDK](../user/project/clusters/index.md#installing-applications) -- Layer: Core Service (Processor) - -GitLab provides [GitLab Managed Apps](../user/project/clusters/index.md#installing-applications), -a one-click install for various applications which can be added directly to your configured cluster. -These applications are needed for Review Apps and deployments when using Auto DevOps. -You can install them after you create a cluster. This includes: - -- [Helm](https://helm.sh/docs/) -- [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) -- [Cert-Manager](https://cert-manager.io/docs/) -- [Prometheus](https://prometheus.io/docs/introduction/overview/) -- [GitLab Runner](https://docs.gitlab.com/runner/) -- [JupyterHub](https://jupyter.org) -- [Knative](https://cloud.google.com/knative/) - ## GitLab by request type GitLab provides two "interfaces" for end users to access the service: @@ -896,7 +855,7 @@ instead of `git upload-pack`. If fast SSH key lookups are not enabled, the SSH server reads from the `~git/.ssh/authorized_keys` file to determine what command to run for a given -SSH session. This is kept up to date by an [`AuthorizedKeysWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/workers/authorized_keys_worker.rb) +SSH session. This is kept up to date by an [`AuthorizedKeysWorker`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/workers/authorized_keys_worker.rb) in Rails, scheduled to run whenever an SSH key is modified by a user. [SSH certificates](../administration/operations/ssh_certificates.md) may be used @@ -1035,7 +994,7 @@ GitLab Shell has a configuration file at `/home/git/gitlab-shell/config.yml`. ### Maintenance tasks -[GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master) provides Rake tasks with which you see version information and run a quick check on your configuration to ensure it is configured properly within the application. See [maintenance Rake tasks](../administration/raketasks/maintenance.md). +[GitLab](https://gitlab.com/gitlab-org/gitlab/-/tree/master) provides Rake tasks with which you see version information and run a quick check on your configuration to ensure it is configured properly within the application. See [maintenance Rake tasks](../administration/raketasks/maintenance.md). In a nutshell, do the following: ```shell diff --git a/doc/development/auto_devops.md b/doc/development/auto_devops.md index c127858d3e7..054a3439ef1 100644 --- a/doc/development/auto_devops.md +++ b/doc/development/auto_devops.md @@ -21,7 +21,7 @@ project, the user does not need to explicitly include any pipeline configuration through a [`.gitlab-ci.yml` file](../ci/yaml/README.md). In the absence of a `.gitlab-ci.yml` file, the [Auto DevOps CI -template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) +template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) is used implicitly to configure the pipeline for the project. This template is a top-level template that includes other sub-templates, which then defines jobs. @@ -29,12 +29,12 @@ which then defines jobs. Some jobs use images that are built from external projects: - [Auto Build](../topics/autodevops/stages.md#auto-build) uses - [configuration](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Build.gitlab-ci.yml) + [configuration](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Build.gitlab-ci.yml) in which the `build` job uses an image that is built using the [`auto-build-image`](https://gitlab.com/gitlab-org/cluster-integration/auto-build-image) project. - [Auto Deploy](../topics/autodevops/stages.md#auto-deploy) uses - [configuration](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) + [configuration](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) in which the jobs defined in this template use an image that is built using the [`auto-deploy-image`](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) project. By default, the Helm chart defined in @@ -43,7 +43,7 @@ Some jobs use images that are built from external projects: There are extra variables that get passed to the CI jobs when Auto DevOps is enabled that are not present in a normal CI job. These can be found in -[`ProjectAutoDevops`](https://gitlab.com/gitlab-org/gitlab/blob/bf69484afa94e091c3e1383945f60dbe4e8681af/app/models/project_auto_devops.rb). +[`ProjectAutoDevops`](https://gitlab.com/gitlab-org/gitlab/-/blob/bf69484afa94e091c3e1383945f60dbe4e8681af/app/models/project_auto_devops.rb). ## Development environment diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index a96606719d0..0b81d40f585 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -7,28 +7,25 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo # Background migrations -Background migrations can be used to perform data migrations that would -otherwise take a very long time (hours, days, years, etc) to complete. For -example, you can use background migrations to migrate data so that instead of -storing data in a single JSON column the data is stored in a separate table. +Background migrations should be used to perform data migrations whenever a +migration exceeds [the time limits in our guidelines](database_review.md#timing-guidelines-for-migrations). For example, you can use background +migrations to migrate data that's stored in a single JSON column +to a separate table instead. If the database cluster is considered to be in an unhealthy state, background migrations automatically reschedule themselves for a later point in time. ## When To Use Background Migrations -In the vast majority of cases you will want to use a regular Rails migration -instead. Background migrations should be used when migrating _data_ in -tables that have so many rows this process would take hours when performed in a -regular Rails migration. +You should use a background migration when you migrate _data_ in tables that have +so many rows that the process would exceed [the time limits in our guidelines](database_review.md#timing-guidelines-for-migrations) if performed using a regular Rails migration. -Background migrations _may_ also be used when executing numerous single-row queries +- Background migrations should be used when migrating data in [high-traffic tables](migration_style_guide.md#high-traffic-tables). +- Background migrations may also be used when executing numerous single-row queries for every item on a large dataset. Typically, for single-record patterns, runtime is largely dependent on the size of the dataset, hence it should be split accordingly and put into background migrations. - -Background migrations _may not_ be used to perform schema migrations, they -should only be used for data migrations. +- Background migrations should not be used to perform schema migrations. Some examples where background migrations can be useful: @@ -255,12 +252,8 @@ batches instead of doing this one by one: class ScheduleExtractServicesUrl < ActiveRecord::Migration[4.2] disable_ddl_transaction! - class Service < ActiveRecord::Base - self.table_name = 'services' - end - def up - Service.select(:id).in_batches do |relation| + define_batchable_model('services').select(:id).in_batches do |relation| jobs = relation.pluck(:id).map do |id| ['ExtractServicesUrl', [id]] end @@ -286,18 +279,12 @@ this: class ConsumeRemainingExtractServicesUrlJobs < ActiveRecord::Migration[4.2] disable_ddl_transaction! - class Service < ActiveRecord::Base - include ::EachBatch - - self.table_name = 'services' - end - def up # This must be included Gitlab::BackgroundMigration.steal('ExtractServicesUrl') # This should be included, but can be skipped - see below - Service.where(url: nil).each_batch(of: 50) do |batch| + define_batchable_model('services').where(url: nil).each_batch(of: 50) do |batch| range = batch.pluck('MIN(id)', 'MAX(id)').first Gitlab::BackgroundMigration::ExtractServicesUrl.new.perform(*range) @@ -358,25 +345,87 @@ for more details. more pressure on DB than you expect (measure on staging, or ask someone to measure on production). 1. Make sure to know how much time it'll take to run all scheduled migrations. -1. Provide an estimation section in the description, explaining timings from the - linked query plans and batches as described in the migration. +1. Provide an estimation section in the description, estimating both the total migration + run time and the query times for each background migration job. Explain plans for each query + should also be provided. For example, assuming a migration that deletes data, include information similar to the following section: - ```ruby + ```plaintext Background Migration Details: 47600 items to delete batch size = 1000 - 47600 / 1000 = 48 loops + 47600 / 1000 = 48 batches Estimated times per batch: - - 900ms for select statement with 1000 items - - 2100ms for delete statement with 1000 items - Total: ~3sec per batch + - 820ms for select statement with 1000 items (see linked explain plan) + - 900ms for delete statement with 1000 items (see linked explain plan) + Total: ~2 sec per batch - 2 mins delay per loop (safe for the given total time per batch) + 2 mins delay per batch (safe for the given total time per batch) - 48 * ( 120 + 3) = ~98.4 mins to run all the scheduled jobs + 48 batches * 2 min per batch = 96 mins to run all the scheduled jobs ``` + + The execution time per batch (2 sec in this example) is not included in the calculation + for total migration time. The jobs are scheduled 2 minutes apart without knowledge of + the execution time. + +## Additional tips and strategies + +### Nested batching + +A strategy to make the migration run faster is to schedule larger batches, and then use `EachBatch` +within the background migration to perform multiple statements. + +The background migration helpers that queue multiple jobs such as +`queue_background_migration_jobs_by_range_at_intervals` use [`EachBatch`](iterating_tables_in_batches.md). +The example above has batches of 1000, where each queued job takes two seconds. If the query has been optimized +to make the time for the delete statement within the [query performance guidelines](query_performance.md), +1000 may be the largest number of records that can be deleted in a reasonable amount of time. + +The minimum and most common interval for delaying jobs is two minutes. This results in two seconds +of work for each two minute job. There's nothing that prevents you from executing multiple delete +statements in each background migration job. + +Looking at the example above, you could alternatively do: + +```plaintext +Background Migration Details: + +47600 items to delete +batch size = 10_000 +47600 / 10_000 = 5 batches + +Estimated times per batch: +- Records are updated in sub-batches of 1000 => 10_000 / 1000 = 10 total updates +- 820ms for select statement with 1000 items (see linked explain plan) +- 900ms for delete statement with 1000 items (see linked explain plan) +Sub-batch total: ~2 sec per sub-batch, +Total batch time: 2 * 10 = 20 sec per batch + +2 mins delay per batch + +5 batches * 2 min per batch = 10 mins to run all the scheduled jobs +``` + +The batch time of 20 seconds still fits comfortably within the two minute delay, yet the total run +time is cut by a tenth from around 100 minutes to 10 minutes! When dealing with large background +migrations, this can cut the total migration time by days. + +When batching in this way, it is important to look at query times on the higher end +of the table or relation being updated. `EachBatch` may generate some queries that become much +slower when dealing with higher ID ranges. + +### Delay time + +When looking at the batch execution time versus the delay time, the execution time +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. + +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/changelog.md b/doc/development/changelog.md index 6412c303735..f0c37af42ab 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -11,56 +11,93 @@ file, as well as information and history about our changelog process. ## Overview -Each bullet point, or **entry**, in our [`CHANGELOG.md`](https://gitlab.com/gitlab-org/gitlab/blob/master/CHANGELOG.md) file is -generated from a single data file in the [`changelogs/unreleased/`](https://gitlab.com/gitlab-org/gitlab/tree/master/changelogs/unreleased/). -The file is expected to be a [YAML](https://en.wikipedia.org/wiki/YAML) file in the -following format: +Each bullet point, or **entry**, in our +[`CHANGELOG.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/CHANGELOG.md) +file is generated from the subject line of a Git commit. Commits are included +when they contain the `Changelog` [Git trailer](https://git-scm.com/docs/git-interpret-trailers). +When generating the changelog, author and merge request details are added +automatically. -```yaml ---- -title: "Change[log]s" -merge_request: 1972 -author: Black Sabbath @bsabbath -type: added +The `Changelog` trailer accepts the following values: + +- `added`: New feature +- `fixed`: Bug fix +- `changed`: Feature change +- `deprecated`: New deprecation +- `removed`: Feature removal +- `security`: Security fix +- `performance`: Performance improvement +- `other`: Other + +An example of a Git commit to include in the changelog is the following: + +```plaintext +Update git vendor to gitlab + +Now that we are using gitaly to compile git, the git version isn't known +from the manifest, instead we are getting the gitaly version. Update our +vendor field to be `gitlab` to avoid cve matching old versions. + +Changelog: changed ``` -The `merge_request` value is a reference to a merge request that adds this -entry, and the `author` key (format: `<full name> <GitLab username>`) is used to give attribution to community -contributors. **Both are optional**. -The `type` field maps the category of the change, -valid options are: added, fixed, changed, deprecated, removed, security, performance, other. **Type field is mandatory**. +### Overriding the associated merge request + +GitLab automatically links the merge request to the commit when generating the +changelog. If you want to override the merge request to link to, you can specify +an alternative merge request using the `MR` trailer: + +```plaintext +Update git vendor to gitlab -Community contributors and core team members are encouraged to add their name to -the `author` field. GitLab team members **should not**. +Now that we are using gitaly to compile git, the git version isn't known +from the manifest, instead we are getting the gitaly version. Update our +vendor field to be `gitlab` to avoid cve matching old versions. + +Changelog: changed +MR: https://gitlab.com/foo/bar/-/merge_requests/123 +``` + +The value must be the full URL of the merge request. + +### GitLab Enterprise changes + +If a change is for GitLab Enterprise Edition, you must also add the trailer `EE: +true`: + +```plaintext +Update git vendor to gitlab + +Now that we are using gitaly to compile git, the git version isn't known +from the manifest, instead we are getting the gitaly version. Update our +vendor field to be `gitlab` to avoid cve matching old versions. + +Changelog: changed +MR: https://gitlab.com/foo/bar/-/merge_requests/123 +EE: true +``` ## What warrants a changelog entry? - Any change that introduces a database migration, whether it's regular, post, or data migration, **must** have a changelog entry, even if it is behind a - disabled feature flag. Since the migration is executed on [GitLab FOSS](https://gitlab.com/gitlab-org/gitlab-foss/), - the changelog for database schema changes should be written to the - `changelogs/unreleased/` directory, even when other elements of that change affect only GitLab EE. - + disabled feature flag. - [Security fixes](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md) - **must** have a changelog entry, without `merge_request` value - and with `type` set to `security`. -- Any user-facing change **must** have a changelog entry. This includes both visual changes (regardless of how minor), and changes to the rendered DOM which impact how a screen reader may announce the content. -- Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry. See the [complete list what comprises a GraphQL breaking change](api_graphql_styleguide.md#breaking-changes). -- Any change that introduces an [Advanced Search migration](elasticsearch.md#creating-a-new-advanced-search-migration) **must** have a changelog entry. -- Performance improvements **should** have a changelog entry. -- _Any_ contribution from a community member, no matter how small, **may** have - a changelog entry regardless of these guidelines if the contributor wants one. - Example: "Fixed a typo on the search results page." -- Any docs-only changes **should not** have a changelog entry. -- For changes related to feature flags, use [feature flag guide](feature_flags/index.md#changelog) to determine the changelog entry. -- Any change that adds new Usage Data metrics, sets the status of existing ones to `removed`, and changes that need to be documented in Product Intelligence [Metrics Dictionary](usage_ping/dictionary.md) **should** have a changelog entry. -- A change that adds snowplow events **should** have a changelog entry - -- A fix for a regression introduced and then fixed in the same release (i.e., + **must** have a changelog entry, with `Changelog` trailer set to `security`. +- Any user-facing change **must** have a changelog entry. Example: "GitLab now + uses system fonts for all text." +- Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry. + See the [complete list what comprises a GraphQL breaking change](api_graphql_styleguide.md#breaking-changes). +- Any change that introduces an [Advanced Search migration](elasticsearch.md#creating-a-new-advanced-search-migration) + **must** have a changelog entry. +- A fix for a regression introduced and then fixed in the same release (such as fixing a bug introduced during a monthly release candidate) **should not** have a changelog entry. -- Any developer-facing change (e.g., refactoring, technical debt remediation, - test suite changes) **should not** have a changelog entry. Example: "Reduce +- Any developer-facing change (such as refactoring, technical debt remediation, + or test suite changes) **should not** have a changelog entry. Example: "Reduce database records created during Cycle Analytics model spec." +- _Any_ contribution from a community member, no matter how small, **may** have + a changelog entry regardless of these guidelines if the contributor wants one. ## Writing good changelog entries @@ -105,215 +142,49 @@ about _where_ and _why_ the change was made? ## How to generate a changelog entry -A `bin/changelog` script is available to generate the changelog entry file -automatically. +Git trailers are added when committing your changes. This can be done using your +text editor of choice. Adding the trailer to an existing commit requires either +amending to the commit (if it's the most recent one), or an interactive rebase +using `git rebase -i`. -Its simplest usage is to provide the value for `title`: +To update the last commit, run the following: -```plaintext -bin/changelog 'Hey DZ, I added a feature to GitLab!' +```shell +git commit --amend ``` -If you want to generate a changelog entry for GitLab EE, you must pass -the `--ee` option: +You can then add the `Changelog` trailer to the commit message. If you had +already pushed prior commits to your remote branch, you have to force push +the new commit: -```plaintext -bin/changelog --ee 'Hey DZ, I added a feature to GitLab!' +```shell +git push -f origin your-branch-name ``` -All entries in the `CHANGELOG.md` file apply to all editions of GitLab. -Changelog updates are based on a common [GitLab codebase](https://gitlab.com/gitlab-org/gitlab/), -and are mirrored without proprietary code to [GitLab FOSS](https://gitlab.com/gitlab-org/gitlab-foss/) (also known as GitLab Community Edition). +To edit older (or multiple commits), use `git rebase -i HEAD~N` where `N` is the +last N number of commits to rebase. Let's say you have 3 commits on your branch: +A, B, and C. If you want to update commit B, you need to run: -At this point the script would ask you to select the category of the change (mapped to the `type` field in the entry): - -```plaintext ->> Please specify the category of your change: -1. New feature -2. Bug fix -3. Feature change -4. New deprecation -5. Feature removal -6. Security fix -7. Performance improvement -8. Other +```shell +git rebase -i HEAD~2 ``` -The entry filename is based on the name of the current Git branch. If you run -the command above on a branch called `feature/hey-dz`, it generates a -`changelogs/unreleased/feature-hey-dz.yml` file. - -The command outputs the path of the generated file and its contents: +This starts an interactive rebase session for the last two commits. When +started, Git presents you with a text editor with contents along the lines of +the following: ```plaintext -create changelogs/unreleased/my-feature.yml ---- -title: Hey DZ, I added a feature to GitLab! -merge_request: -author: -type: +pick B Subject of commit B +pick C Subject of commit C ``` -### Arguments - -| Argument | Shorthand | Purpose | -| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| [`--amend`](#--amend) | | Amend the previous commit | -| [`--force`](#--force-or--f) | `-f` | Overwrite an existing entry | -| [`--merge-request`](#--merge-request-or--m) | `-m` | Set merge request ID | -| [`--dry-run`](#--dry-run-or--n) | `-n` | Don't actually write anything, just print | -| [`--git-username`](#--git-username-or--u) | `-u` | Use Git user.name configuration as the author | -| [`--type`](#--type-or--t) | `-t` | The category of the change, valid options are: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `other` | -| [`--ee`](#how-to-generate-a-changelog-entry) | | Create an EE changelog -| `--help` | `-h` | Print help message | - -#### `--amend` - -You can pass the **`--amend`** argument to automatically stage the generated -file and amend it to the previous commit. - -If you use **`--amend`** and don't provide a title, it uses -the "subject" of the previous commit, which is the first line of the commit -message: - -```plaintext -$ git show --oneline -ab88683 Added an awesome new feature to GitLab - -$ bin/changelog --amend -create changelogs/unreleased/feature-hey-dz.yml ---- -title: Added an awesome new feature to GitLab -merge_request: -author: -type: -``` - -#### `--force` or `-f` - -Use **`--force`** or **`-f`** to overwrite an existing changelog entry if it -already exists. - -```plaintext -$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -error changelogs/unreleased/feature-hey-dz.yml already exists! Use `--force` to overwrite. - -$ bin/changelog 'Hey DZ, I added a feature to GitLab!' --force -create changelogs/unreleased/feature-hey-dz.yml ---- -title: Hey DZ, I added a feature to GitLab! -merge_request: 1983 -author: -type: -``` - -#### `--merge-request` or `-m` - -Use the **`--merge-request`** or **`-m`** argument to provide the -`merge_request` value: - -```plaintext -$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -m 1983 -create changelogs/unreleased/feature-hey-dz.yml ---- -title: Hey DZ, I added a feature to GitLab! -merge_request: 1983 -author: -type: -``` - -#### `--dry-run` or `-n` - -Use the **`--dry-run`** or **`-n`** argument to prevent actually writing or -committing anything: - -```plaintext -$ bin/changelog --amend --dry-run -create changelogs/unreleased/feature-hey-dz.yml ---- -title: Added an awesome new feature to GitLab -merge_request: -author: -type: - -$ ls changelogs/unreleased/ -``` - -#### `--git-username` or `-u` - -Use the **`--git-username`** or **`-u`** argument to automatically fill in the -`author` value with your configured Git `user.name` value: - -```plaintext -$ git config user.name -Jane Doe - -$ bin/changelog -u 'Hey DZ, I added a feature to GitLab!' -create changelogs/unreleased/feature-hey-dz.yml ---- -title: Hey DZ, I added a feature to GitLab! -merge_request: -author: Jane Doe -type: -``` - -#### `--type` or `-t` - -Use the **`--type`** or **`-t`** argument to provide the `type` value: - -```plaintext -$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -t added -create changelogs/unreleased/feature-hey-dz.yml ---- -title: Hey DZ, I added a feature to GitLab! -merge_request: -author: -type: added -``` - -#### `--ee` - -Use the **`--ee`** argument to create an EE changelog: - -```plaintext -$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -ee -create ee/changelogs/unreleased/feature-hey-dz.yml ---- -title: Hey DZ, I added a feature to GitLab! -merge_request: -author: -type: added -``` +To update commit B, change the word `pick` to `reword`, then save and quit the +editor. Once closed, Git presents you with a new text editor instance to edit +the commit message of commit B. Add the trailer, then save and quit the editor. +If all went well, commit B is now updated. -### History and Reasoning - -Our `CHANGELOG` file was previously updated manually by each contributor that -felt their change warranted an entry. When two merge requests added their own -entries at the same spot in the list, it created a merge conflict in one as soon -as the other was merged. When we had dozens of merge requests fighting for the -same changelog entry location, this quickly became a major source of merge -conflicts and delays in development. - -This led us to a [boring solution](https://about.gitlab.com/handbook/values/#boring-solutions) of "add your entry in a random location in -the list." This actually worked pretty well as we got further along in each -monthly release cycle, but at the start of a new cycle, when a new version -section was added and there were fewer places to "randomly" add an entry, the -conflicts became a problem again until we had a sufficient number of entries. - -On top of all this, it created an entirely different headache for -[release managers](https://gitlab.com/gitlab-org/release/docs/blob/master/quickstart/release-manager.md) -when they cherry-picked a commit into a stable branch for a patch release. If -the commit included an entry in the `CHANGELOG`, it would include the entire -changelog for the latest version in `master`, so the release manager would have -to manually remove the later entries. They often would have had to do this -multiple times per patch release. This was compounded when we had to release -multiple patches at once due to a security issue. - -We needed to automate all of this manual work. So we -[started brainstorming](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/17826). -After much discussion we settled on the current solution of one file per entry, -and then compiling the entries into the overall `CHANGELOG.md` file during the -[release process](https://gitlab.com/gitlab-org/release-tools). +For more information about interactive rebases, take a look at [the Git +documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History). --- diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md index 56e91acbc4a..b0de00648ba 100644 --- a/doc/development/chaos_endpoints.md +++ b/doc/development/chaos_endpoints.md @@ -47,7 +47,7 @@ Replace `secret` with your own secret token. After you have enabled the chaos endpoints and restarted the application, you can start testing using the endpoints. By default, when invoking a chaos endpoint, the web worker process which receives the request handles it. This means, for example, that if the Kill -operation is invoked, the Puma or Unicorn worker process handling the request is killed. To test these operations in Sidekiq, the `async` parameter on +operation is invoked, the Puma worker process handling the request is killed. To test these operations in Sidekiq, the `async` parameter on each endpoint can be set to `true`. This runs the chaos process in a Sidekiq worker. ## Memory leaks @@ -70,7 +70,8 @@ GET /-/chaos/leakmem?memory_mb=1024&duration_s=50&async=true | `async` | boolean | no | Set to true to leak memory in a Sidekiq background worker process | ```shell -curl "http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10" --header 'X-Chaos-Secret: secret' +curl "http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10" \ + --header 'X-Chaos-Secret: secret' curl "http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10&token=secret" ``` @@ -79,7 +80,6 @@ curl "http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10&token=s This endpoint attempts to fully utilise a single core, at 100%, for the given period. Depending on your rack server setup, your request may timeout after a predetermined period (normally 60 seconds). -If you're using Unicorn, this is done by killing the worker process. ```plaintext GET /-/chaos/cpu_spin @@ -93,7 +93,8 @@ GET /-/chaos/cpu_spin?duration_s=50&async=true | `async` | boolean | no | Set to true to consume CPU in a Sidekiq background worker process | ```shell -curl "http://localhost:3000/-/chaos/cpu_spin?duration_s=60" --header 'X-Chaos-Secret: secret' +curl "http://localhost:3000/-/chaos/cpu_spin?duration_s=60" \ + --header 'X-Chaos-Secret: secret' curl "http://localhost:3000/-/chaos/cpu_spin?duration_s=60&token=secret" ``` @@ -103,7 +104,6 @@ This endpoint attempts to fully utilise a single core, and interleave it with DB This endpoint can be used to model yielding execution to another threads when running concurrently. Depending on your rack server setup, your request may timeout after a predetermined period (normally 60 seconds). -If you're using Unicorn, this is done by killing the worker process. ```plaintext GET /-/chaos/db_spin @@ -118,7 +118,8 @@ GET /-/chaos/db_spin?duration_s=50&async=true | `async` | boolean | no | Set to true to perform the operation in a Sidekiq background worker process | ```shell -curl "http://localhost:3000/-/chaos/db_spin?interval_s=1&duration_s=60" --header 'X-Chaos-Secret: secret' +curl "http://localhost:3000/-/chaos/db_spin?interval_s=1&duration_s=60" \ + --header 'X-Chaos-Secret: secret' curl "http://localhost:3000/-/chaos/db_spin?interval_s=1&duration_s=60&token=secret" ``` @@ -140,7 +141,8 @@ GET /-/chaos/sleep?duration_s=50&async=true | `async` | boolean | no | Set to true to sleep in a Sidekiq background worker process | ```shell -curl "http://localhost:3000/-/chaos/sleep?duration_s=60" --header 'X-Chaos-Secret: secret' +curl "http://localhost:3000/-/chaos/sleep?duration_s=60" \ + --header 'X-Chaos-Secret: secret' curl "http://localhost:3000/-/chaos/sleep?duration_s=60&token=secret" ``` @@ -200,7 +202,8 @@ POST /-/chaos/gc Example request: ```shell -curl --request POST "http://localhost:3000/-/chaos/gc" --header 'X-Chaos-Secret: secret' +curl --request POST "http://localhost:3000/-/chaos/gc" \ + --header 'X-Chaos-Secret: secret' curl --request POST "http://localhost:3000/-/chaos/gc?token=secret" ``` diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md index a05916178a9..14a313daba8 100644 --- a/doc/development/cicd/cicd_reference_documentation_guide.md +++ b/doc/development/cicd/cicd_reference_documentation_guide.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 965ab3610dd..025d63f4a62 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, concepts, howto --- @@ -67,7 +67,7 @@ The communication between runners and the Rails server occurs through a set of A the `Runner API Gateway`. We can register, delete, and verify runners, which also causes read/write queries to the database. After a runner is connected, -it keeps asking for the next job to execute. This invokes the [`RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/services/ci/register_job_service.rb) +it keeps asking for the next job to execute. This invokes the [`RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/register_job_service.rb) which picks the next job and assigns it to the runner. At this point the job transitions to a `running` state, which again triggers `ProcessPipelineService` due to the status change. For more details read [Job scheduling](#job-scheduling)). @@ -103,7 +103,7 @@ A job with the `created` state isn't seen by the runner yet. To make it possible When the runner is connected, it requests the next `pending` job to run by polling the server continuously. NOTE: -API endpoints used by the runner to interact with GitLab are defined in [`lib/api/ci/runner.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/ci/runner.rb) +API endpoints used by the runner to interact with GitLab are defined in [`lib/api/ci/runner.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/ci/runner.rb) After the server receives the request it selects a `pending` job based on the [`Ci::RegisterJobService` algorithm](#ciregisterjobservice), then assigns and sends the job to the runner. @@ -121,7 +121,7 @@ Once the runner is [registered](https://docs.gitlab.com/runner/register/) using The runner initiates the communication by requesting jobs to execute with `POST /api/v4/jobs/request`. Although this polling generally happens every few seconds we leverage caching via HTTP headers to reduce the server-side work load if the job queue doesn't change. -This API endpoint runs [`Ci::RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/services/ci/register_job_service.rb), which: +This API endpoint runs [`Ci::RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/register_job_service.rb), which: 1. Picks the next job to run from the pool of `pending` jobs 1. Assigns it to the runner @@ -185,17 +185,3 @@ Watch a walkthrough of this feature in details in the video below. <figure class="video-container"> <iframe src="https://www.youtube.com/embed/NmdWRGT8kZg" frameborder="0" allowfullscreen="true"> </iframe> </figure> - -## External pipeline validation service - -The [external CI/CD pipeline validation service](../../administration/external_pipeline_validation.md) -is available for use on self-managed GitLab instances, but is not in use on GitLab.com. -It is configured with [environment variables](../../administration/environment_variables.md) -on the instance. - -To enable the feature on GitLab.com, enable the `ci_external_validation_service` -[feature flag](../feature_flags/index.md). The valid "Not accepted" response code -for GitLab.com is `406` only. - -For more details, see the linked issues and MRs in the -[feature flag rollout issue](https://gitlab.com/gitlab-org/gitlab/-/issues/325982). diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index fc342794919..8331985697e 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -307,6 +307,26 @@ include: - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/v13.0.1-ee/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml ``` +### Use a feature flag to roll out a `latest` template + +With a major version release like 13.0 or 14.0, [stable templates](#stable-version) must be +updated with their corresponding [latest template versions](#latest-version). +It may be hard to gauge the impact of this change, so use the `redirect_to_latest_template_<name>` +feature flag to test the impact on a subset of users. Using a feature flag can help +reduce the risk of reverts or rollbacks on production. + +For example, to redirect the stable `Jobs/Deploy` template to its latest template in 25% of +projects on `gitlab.com`: + +```shell +/chatops run feature set redirect_to_latest_template_jobs_deploy 25 --actors +``` + +After you're confident the latest template can be moved to stable: + +1. Update the stable template with the content of the latest version. +1. Remove the corresponding feature flag. + ### Further reading There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/17716) about diff --git a/doc/development/code_review.md b/doc/development/code_review.md index b91e27b7051..df09b27c6b4 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -418,13 +418,13 @@ WARNING: - Start a new merge request pipeline with the `Run pipeline` button in the merge request's "Pipelines" tab, and enable "Merge When Pipeline Succeeds" (MWPS). Note that: - - If **[master is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), + - If **[main is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), do not merge the merge request** except for [very specific cases](https://about.gitlab.com/handbook/engineering/workflow/#criteria-for-merging-during-broken-master). For other cases, follow these [handbook instructions](https://about.gitlab.com/handbook/engineering/workflow/#merging-during-broken-master). - If the **latest [Pipeline for Merged Results](../ci/merge_request_pipelines/pipelines_for_merged_results/#pipelines-for-merged-results)** finished less than 2 hours ago, you might merge without starting a new pipeline as the merge request is close - enough to `master`. + enough to `main`. - When you set the MR to "Merge When Pipeline Succeeds", you should take over subsequent revisions for anything that would be spotted after that. - For merge requests that have had [Squash and @@ -434,11 +434,11 @@ WARNING: Thanks to **Pipeline for Merged Results**, authors no longer have to rebase their branch as frequently anymore (only when there are conflicts) because the Merge -Results Pipeline already incorporate the latest changes from `master`. +Results Pipeline already incorporate the latest changes from `main`. This results in faster review/merge cycles because maintainers don't have to ask for a final rebase: instead, they only have to start a MR pipeline and set MWPS. This step brings us very close to the actual Merge Trains feature by testing the -Merge Results against the latest `master` at the time of the pipeline creation. +Merge Results against the latest `main` at the time of the pipeline creation. ### Community contributions diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 26a32464041..2fe08f78aed 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -27,7 +27,7 @@ To get an overview of GitLab community membership, including those that would re your contributions, visit [the community roles page](community_roles.md). If you want to know how the GitLab [core team](https://about.gitlab.com/community/core-team/) -operates, see [the GitLab contributing process](https://gitlab.com/gitlab-org/gitlab/blob/master/PROCESS.md). +operates, see [the GitLab contributing process](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md). GitLab Inc engineers should refer to the [engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/). diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index dfabeca34ce..840434ebbc3 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -14,7 +14,7 @@ submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an award emoji and/or join the discussion. -Please submit bugs using the ['Bug' issue template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/issue_templates/Bug.md) provided on the issue tracker. +Please submit bugs using the ['Bug' issue template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Bug.md) provided on the issue tracker. The text in the parenthesis is there to help you with what to include. Omit it when submitting the actual issue. You can copy-paste it and then edit as you see fit. @@ -311,12 +311,12 @@ We automatically add the ~"Accepting merge requests" label to issues that match the [triage policy](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#accepting-merge-requests). We recommend people that have never contributed to any open source project to -look for issues labeled `~"Accepting merge requests"` with a [weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1) or the `~"Good for new contributors"` [label](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=good%20for%20new%20contributors&assignee_id=None) attached to it. +look for issues labeled `~"Accepting merge requests"` with a [weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1) or the `~"Good for new contributors"` [label](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&state=opened&label_name[]=good%20for%20new%20contributors&assignee_id=None) attached to it. More experienced contributors are very welcome to tackle [any of them](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None). For more complex features that have a weight of 2 or more and clear scope, we recommend looking at issues -with the [label `~"Community Challenge"`](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Accepting%20merge%20requests&label_name[]=Community%20challenge). +with the [label `~"Community Challenge"`](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&state=opened&label_name[]=Accepting%20merge%20requests&label_name[]=Community%20challenge). If your MR for the `~"Community Challenge"` issue gets merged, you will also have a chance to win a custom GitLab merchandise. @@ -325,7 +325,7 @@ the [appropriate product manager](https://about.gitlab.com/handbook/product/#who as soon as possible. The product manager will then pull in appropriate GitLab team members to further discuss scope, design, and technical considerations. This will ensure that your contribution is aligned with the GitLab product and minimize -any rework and delay in getting it merged into master. +any rework and delay in getting it merged into main. GitLab team members who apply the ~"Accepting merge requests" label to an issue should update the issue description with a responsible product manager, inviting @@ -358,7 +358,7 @@ code snippet right after your description in a new line: `~feature`. Please keep feature proposals as small and simple as possible, complex ones might be edited to make them small and simple. -Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/issue_templates/Feature%20proposal%20-%20detailed.md) provided on the issue tracker. +Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal%20-%20detailed.md) provided on the issue tracker. For changes in the interface, it is helpful to include a mockup. Issues that add to, or change, the interface should be given the ~"UX" label. This will allow the UX team to provide input and guidance. You may diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 922bc52773b..783cf7af6fc 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -44,9 +44,9 @@ request is as follows: 1. [Fork](../../user/project/repository/forking_workflow.md) the project into your personal namespace (or group) on GitLab.com. -1. Create a feature branch in your fork (don't work off `master`). +1. Create a feature branch in your fork (don't work off your [default branch](../../user/project/repository/branches/default.md)). 1. Write [tests](../rake_tasks.md#run-tests) and code. -1. [Generate a changelog entry with `bin/changelog`](../changelog.md) +1. [Ensure a changelog is created](../changelog.md). 1. If you are writing documentation, make sure to follow the [documentation guidelines](../documentation/index.md). 1. Follow the [commit messages guidelines](#commit-messages-guidelines). @@ -54,7 +54,7 @@ request is as follows: commits by [squashing them](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing), but do not change the commit history if you're working on shared branches though. 1. Push the commit(s) to your working branch in your fork. -1. Submit a merge request (MR) to the `master` branch in the main GitLab project. +1. Submit a merge request (MR) to the `main` branch in the main GitLab project. 1. Your merge request needs at least 1 approval, but depending on your changes you might need additional approvals. Refer to the [Approval guidelines](../code_review.md#approval-guidelines). 1. You don't have to select any specific approvers, but you can if you really want @@ -140,7 +140,7 @@ Commit messages should follow the guidelines below, for reasons explained by Chr **Important notes:** -- If the guidelines are not met, the MR may not pass the [Danger checks](https://gitlab.com/gitlab-org/gitlab/blob/master/danger/commit_messages/Dangerfile). +- If the guidelines are not met, the MR may not pass the [Danger checks](https://gitlab.com/gitlab-org/gitlab/-/blob/master/danger/commit_messages/Dangerfile). - Consider enabling [Squash and merge](../../user/project/merge_requests/squash_and_merge.md#squash-and-merge) if your merge request includes "Applied suggestion to X files" commits, so that Danger can ignore those. - The prefixes in the form of `[prefix]` and `prefix:` are allowed (they can be all lowercase, as long @@ -196,12 +196,12 @@ the contribution acceptance criteria below: exposing a bug in existing code). Every new class should have corresponding unit tests, even if the class is exercised at a higher level, such as a feature test. - If a failing CI build seems to be unrelated to your contribution, you can try - restarting the failing CI job, rebasing from `master` to bring in updates that + restarting the failing CI job, rebasing from `main` to bring in updates that may resolve the failure, or if it has not been fixed yet, ask a developer to help you fix the test. 1. The MR initially contains a few logically organized commits. 1. The changes can merge without problems. If not, you should rebase if you're the - only one working on your feature branch, otherwise merge `master`. + only one working on your feature branch, otherwise merge `main`. 1. Only one specific issue is fixed or one specific feature is implemented. Do not combine things; send separate merge requests for each issue or feature. 1. Migrations should do only one thing (e.g., create a table, move data to a new @@ -263,7 +263,7 @@ request: 1. [The upgrade guide](../../update/upgrading_from_source.md). 1. The [GitLab Installation Guide](../../install/installation.md#1-packages-and-dependencies). 1. The [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit). -1. The [CI environment preparation](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/prepare_build.sh). +1. The [CI environment preparation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/prepare_build.sh). 1. The [Omnibus package creator](https://gitlab.com/gitlab-org/omnibus-gitlab). 1. The [Cloud Native GitLab Dockerfiles](https://gitlab.com/gitlab-org/build/CNG) diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index 7fb1e11b303..68268027b73 100644 --- a/doc/development/dangerbot.md +++ b/doc/development/dangerbot.md @@ -45,7 +45,7 @@ bin/rake danger_local ## Operation -On startup, Danger reads a [`Dangerfile`](https://gitlab.com/gitlab-org/gitlab/blob/master/Dangerfile) +On startup, Danger reads a [`Dangerfile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/Dangerfile) from the project root. Danger code in GitLab is decomposed into a set of helpers and plugins, all within the [`danger/`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/danger/) subdirectory, so ours just tells Danger to load it all. Danger then runs diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md index aa3915cd4b6..3308ebfcaae 100644 --- a/doc/development/database/pagination_guidelines.md +++ b/doc/development/database/pagination_guidelines.md @@ -41,7 +41,7 @@ With pagination, the data is split into equal pieces (pages). On the first visit ### Pick the right approach -Let the database handle the pagination, filtering, and data retrieval. Implementing in-memory pagination on the backend (`paginate_array` from kaminari) or on the frontend (JavaScript) might work for a few hundreds of records. If application limits are not defined, things can get out of control quickly. +Let the database handle the pagination, filtering, and data retrieval. Implementing in-memory pagination on the backend (`paginate_array` from Kaminari) or on the frontend (JavaScript) might work for a few hundreds of records. If application limits are not defined, things can get out of control quickly. ### Reduce complexity @@ -78,7 +78,7 @@ Infinite scroll can use keyset pagination without affecting the user experience ### Offset pagination -The most common way to paginate lists is using offset-based pagination (UI and REST API). It's backed by the popular [kaminari](https://github.com/kaminari/kaminari) Ruby gem, which provides convenient helper methods to implement pagination on ActiveRecord queries. +The most common way to paginate lists is using offset-based pagination (UI and REST API). It's backed by the popular [Kaminari](https://github.com/kaminari/kaminari) Ruby gem, which provides convenient helper methods to implement pagination on ActiveRecord queries. Offset-based pagination is leveraging the `LIMIT` and `OFFSET` SQL clauses to take out a specific slice from the table. @@ -97,9 +97,9 @@ Notice that the query also orders the rows by the primary key (`id`). When pagin Example pagination bar: - + -The kaminari gem renders a nice pagination bar on the UI with page numbers and optionally quick shortcuts the next, previous, first, and last page buttons. To render these buttons, kaminari needs to know the number of rows, and for that, a count query is executed. +The Kaminari gem renders a nice pagination bar on the UI with page numbers and optionally quick shortcuts the next, previous, first, and last page buttons. To render these buttons, Kaminari needs to know the number of rows, and for that, a count query is executed. ```sql SELECT COUNT(*) FROM issues WHERE project_id = 1 @@ -158,7 +158,7 @@ Here we're leveraging the ordered property of the b-tree database index. Values Kaminari by default executes a count query to determine the number of pages for rendering the page links. Count queries can be quite expensive for a large table, in an unfortunate scenario the queries will simply time out. -To work around this, we can run kaminari without invoking the count SQL query. +To work around this, we can run Kaminari without invoking the count SQL query. ```ruby Issue.where(project_id: 1).page(1).per(20).without_count @@ -311,5 +311,5 @@ Using keyset pagination outside of GraphQL is not straightforward. We have the l Keyset pagination provides stable performance regardless of the number of pages we moved forward. To achieve this performance, the paginated query needs an index that covers all the columns in the `ORDER BY` clause, similarly to the offset pagination. ### General performance guidelines - + See the [pagination general performance guidelines page](pagination_performance_guidelines.md). diff --git a/doc/development/database/strings_and_the_text_data_type.md b/doc/development/database/strings_and_the_text_data_type.md index 6fbb95c4f60..688d811b897 100644 --- a/doc/development/database/strings_and_the_text_data_type.md +++ b/doc/development/database/strings_and_the_text_data_type.md @@ -34,11 +34,9 @@ but only for updating the declaration of the columns. We can then validate it at `VALIDATE CONSTRAINT`, which requires only a `SHARE UPDATE EXCLUSIVE LOCK` (only conflicts with other validations and index creation while it allows reads and writes). -### Exceptions - -Text columns used by `attr_encrypted` are not required to have a limit, because the length of the -text after encryption may be longer than the text itself. Instead, you can use an Active Record -length validation on the attribute. +NOTE: +Don't use text columns for `attr_encrypted` attributes. Use a +[`:binary` column](../migration_style_guide.md#encrypted-attributes) instead. ## Create a new table with text columns diff --git a/doc/development/db_dump.md b/doc/development/db_dump.md index 505305c860a..0c63bf06e07 100644 --- a/doc/development/db_dump.md +++ b/doc/development/db_dump.md @@ -21,7 +21,7 @@ large database imports. echo "postgresql['checkpoint_segments'] = 64" | sudo tee -a /etc/gitlab/gitlab.rb sudo touch /etc/gitlab/skip-auto-reconfigure sudo gitlab-ctl reconfigure -sudo gitlab-ctl stop unicorn +sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq ``` diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index 2d092b24d65..07a29b17ddc 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/index.md @@ -24,8 +24,13 @@ deprecated. A feature can be deprecated at any time, provided there is a viable alternative. +Deprecations should be announced via [release posts](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations). + ## When can a feature be removed/changed? +Generally, feature or configuration can be removed/changed only on major release. +It also should be [deprecated in advance](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations). + For API removals, see the [GraphQL](../../api/graphql/index.md#deprecation-and-removal-process) and [GitLab API](../../api/README.md#compatibility-guidelines) guidelines. For configuration removals, see the [Omnibus deprecation policy](https://docs.gitlab.com/omnibus/package-information/deprecation_policy.html). diff --git a/doc/development/diffs.md b/doc/development/diffs.md index 52ba89a4d6e..aaa3340af33 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -156,13 +156,13 @@ Historically, merge request diffs have been calculated by `git diff target...sou `HEAD` of the source branch with the merge base (or a common ancestor) of the target branch and the source's. This solution works well until the target branch starts containing some of the changes introduced by the source branch: Consider the following case, in which the source branch -is `feature_a` and the target is `master`: +is `feature_a` and the target is `main`: -1. Checkout a new branch `feature_a` from `master` and remove `file_a` and `file_b` in it. -1. Add a commit that removes `file_a` to `master`. +1. Checkout a new branch `feature_a` from `main` and remove `file_a` and `file_b` in it. +1. Add a commit that removes `file_a` to `main`. The merge request diff still contains the `file_a` removal while the actual diff compared to -`master`'s `HEAD` has only the `file_b` removal. The diff with such redundant +`main`'s `HEAD` has only the `file_b` removal. The diff with such redundant changes is harder to review. In order to display an up-to-date diff, in GitLab 12.9 we @@ -174,16 +174,16 @@ diff. Until we complete the epics ["use merge refs for diffs"](https://gitlab.com/groups/gitlab-org/-/epics/854) and ["merge conflicts in diffs"](https://gitlab.com/groups/gitlab-org/-/epics/4893), -both options `master (base)` and `master (HEAD)` are available to be displayed in merge requests: +both options `main (base)` and `main (HEAD)` are available to be displayed in merge requests:  -The `master (HEAD)` option is meant to replace `master (base)` in the future. +The `main (HEAD)` option is meant to replace `main (base)` in the future. In order to support comments for both options, diff note positions are stored for -both `master (base)` and `master (HEAD)` versions ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198457) in 12.10). -The position for `master (base)` version is stored in `Note#position` and -`Note#original_position` columns, for `master (HEAD)` version `DiffNotePosition` +both `main (base)` and `main (HEAD)` versions ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198457) in 12.10). +The position for `main (base)` version is stored in `Note#position` and +`Note#original_position` columns, for `main (HEAD)` version `DiffNotePosition` has been introduced. One of the key challenges to deal with when working on merge ref diffs are merge diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index d658794f7e0..5acc8bda6a6 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -78,7 +78,7 @@ You should include a link for your new document in the global navigation (the li left side of the documentation website). To do so, open a second MR, against the [GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/). -We store our global navigation in the [`default-nav.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_data/default-nav.yaml) file, in the +We store our global navigation in the [`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/navigation.yaml) file, in the `content/_data` subdirectory. You can find the GraphQL section under the following line: diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 05aa003d89e..12a1912dd25 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -27,8 +27,8 @@ The source of the documentation exists within the codebase of each GitLab applic | Project | Path | | --- | --- | -| [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) | -| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | +| [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) | +| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) | | [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) | | [Charts](https://gitlab.com/gitlab-org/charts/gitlab) | [`/doc`](https://gitlab.com/gitlab-org/charts/gitlab/tree/master/doc) | @@ -156,7 +156,7 @@ Nanoc layout), which is displayed at the top of the page if defined: - `reading_time`: If you want to add an indication of the approximate reading time of a page, you can set `reading_time` to `true`. This uses a simple - [algorithm](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/lib/helpers/reading_time.rb) + [algorithm](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/lib/helpers/reading_time.rb) to calculate the reading time based on the number of words. ## Move or rename a page @@ -177,8 +177,8 @@ There are two types of redirects: - [GitLab Pages redirects](../../user/project/pages/redirects.md), for users who view the docs on [`docs.gitlab.com`](https://docs.gitlab.com). -The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/master/.gitlab/issue_templates/tw-monthly-tasks.md) -to regularly update the [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_data/redirects.yaml) +The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md) +to regularly update the [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml) file. To add a redirect: @@ -229,6 +229,7 @@ To add a redirect: ```markdown --- redirect_to: '../newpath/to/file/index.md' + remove_date: 'YYYY-MM-DD' --- This document was moved to [another location](../path/to/file/index.md). @@ -295,7 +296,7 @@ Before getting started, make sure you read the introductory section "[contributing to docs](#contributing-to-docs)" above and the [documentation workflow](workflow.md). -- Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/merge_request_templates/Documentation.md) +- Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation.md) - Label the MR `Documentation` (can only be done by people with `developer` access, for example, GitLab team members) - Assign the correct milestone per note below (can only be done by people with `developer` access, for example, GitLab team members) @@ -316,7 +317,8 @@ it increases the work of the release managers. Every GitLab instance includes the documentation, which is available at `/help` (`https://gitlab.example.com/help`). For example, <https://gitlab.com/help>. -The documentation available online on <https://docs.gitlab.com> is deployed every four hours from the `master` branch of GitLab, Omnibus, and Runner. Therefore, +The documentation available online on <https://docs.gitlab.com> is deployed every +four hours from the `main` branch of GitLab, Omnibus, and Runner. Therefore, after a merge request gets merged, it is available online on the same day. However, it's shipped (and available on `/help`) within the milestone assigned to the MR. @@ -392,7 +394,7 @@ This is preferred over static paths, as the helper also works on instances insta ### GitLab `/help` tests -Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/features/help_pages_spec.rb) +Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb) are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) works correctly from `/help`. For example, [GitLab.com's `/help`](https://gitlab.com/help). @@ -411,7 +413,7 @@ on how the left-side navigation menu is built and updated. NOTE: To preview your changes to documentation locally, follow this -[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). +[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). The live preview is currently enabled for the following projects: @@ -458,9 +460,9 @@ In case the review app URL returns 404, follow these steps to debug: If you want to know the in-depth details, here's what's really happening: 1. You manually run the `review-docs-deploy` job in a merge request. -1. The job runs the [`scripts/trigger-build`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/trigger-build) +1. The job runs the [`scripts/trigger-build`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/trigger-build) script with the `docs deploy` flag, which triggers the "Triggered from `gitlab-org/gitlab` 'review-docs-deploy' job" - pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `master`). + pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `main`). 1. The preview URL is shown both at the job output and in the merge request widget. You also get the link to the remote pipeline. 1. In the `gitlab-org/gitlab-docs` project, the pipeline is created and it @@ -477,7 +479,7 @@ The following GitLab features are used among others: - [Multi project pipelines](../../ci/multi_project_pipelines.md) - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/README.md#artifacts) -- [Specific runner](../../ci/runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) +- [Specific runner](../../ci/runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) - [Pipelines for merge requests](../../ci/merge_request_pipelines/index.md) ## Testing @@ -491,7 +493,7 @@ GitLab uses [Danger](https://github.com/danger/danger) for some elements in code review. For docs changes in merge requests, whenever a change to files under `/doc` is made, Danger Bot leaves a comment with further instructions about the documentation process. This is configured in the `Dangerfile` in the GitLab repository under -[/danger/documentation/](https://gitlab.com/gitlab-org/gitlab/tree/master/danger/documentation). +[/danger/documentation/](https://gitlab.com/gitlab-org/gitlab/-/tree/master/danger/documentation). ## Automatic screenshot generator diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index e05f6760ff1..b3d3e2641b7 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -33,7 +33,8 @@ In the Markdown doc for a resource (AKA endpoint): ## API topic template -The following can be used as a template to get started: +Use the following template to help you get started. Be sure to list any +required attributes first in the table. ````markdown ## Descriptive title @@ -50,8 +51,10 @@ Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------|:---------|:----------------------| -| `attribute` | datatype | yes/no | Detailed description. | -| `attribute` | datatype | yes/no | Detailed description. | +| `attribute` | datatype | **{check-circle}** Yes | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | Example request: @@ -147,7 +150,8 @@ This example creates a new group. Be aware of the use of single (`'`) and double (`"`) quotes. ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups" ``` For readability, you can also set up the `--data` by using the following format: @@ -169,7 +173,8 @@ Instead of using JSON or URL-encoding data, you can use `multipart/form-data` wh properly handles data encoding: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "https://gitlab.example.com/api/v4/users/25/keys" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" \ + --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "https://gitlab.example.com/api/v4/users/25/keys" ``` The above example is run by and administrator and will add an SSH public key @@ -195,5 +200,6 @@ exclude specific users when requesting a list of users for a project, you would do something like this: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" --data "skip_users[]=<user_id>" "https://gitlab.example.com/api/v4/projects/<project_id>/users" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" \ + --data "skip_users[]=<user_id>" "https://gitlab.example.com/api/v4/projects/<project_id>/users" ``` diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index d92f58e5501..1b764ada87b 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Documentation deployment process -The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/) +The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/) contains all needed Dockerfiles to build and deploy <https://docs.gitlab.com>. It is heavily inspired by Docker's [Dockerfile](https://github.com/docker/docker.github.io/blob/06ed03db13895bfe867761b6fc2ad40acf6026dd/Dockerfile). @@ -15,10 +15,10 @@ The following Dockerfiles are used. | Dockerfile | Docker image | Description | | ---------- | ------------ | ----------- | -| [`Dockerfile.bootstrap`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.bootstrap) | `gitlab-docs:bootstrap` | Contains all the dependencies that are needed to build the website. If the gems are updated and `Gemfile{,.lock}` changes, the image must be rebuilt. | -| [`Dockerfile.builder.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.builder.onbuild) | `gitlab-docs:builder-onbuild` | Base image to build the docs website. It uses `ONBUILD` to perform all steps and depends on `gitlab-docs:bootstrap`. | -| [`Dockerfile.nginx.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.nginx.onbuild) | `gitlab-docs:nginx-onbuild` | Base image to use for building documentation archives. It uses `ONBUILD` to perform all required steps to copy the archive, and relies upon its parent `Dockerfile.builder.onbuild` that is invoked when building single documentation archives (see the `Dockerfile` of each branch. | -| [`Dockerfile.archives`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.archives) | `gitlab-docs:archives` | Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location. | +| [`Dockerfile.bootstrap`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.bootstrap) | `gitlab-docs:bootstrap` | Contains all the dependencies that are needed to build the website. If the gems are updated and `Gemfile{,.lock}` changes, the image must be rebuilt. | +| [`Dockerfile.builder.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.builder.onbuild) | `gitlab-docs:builder-onbuild` | Base image to build the docs website. It uses `ONBUILD` to perform all steps and depends on `gitlab-docs:bootstrap`. | +| [`Dockerfile.nginx.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.nginx.onbuild) | `gitlab-docs:nginx-onbuild` | Base image to use for building documentation archives. It uses `ONBUILD` to perform all required steps to copy the archive, and relies upon its parent `Dockerfile.builder.onbuild` that is invoked when building single documentation archives (see the `Dockerfile` of each branch. | +| [`Dockerfile.archives`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.archives) | `gitlab-docs:archives` | Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location. | ## How to build the images @@ -36,7 +36,7 @@ and tag all tooling images locally: ``` For each image, there's a manual job under the `images` stage in -[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/.gitlab-ci.yml) which can be invoked at any time. +[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/.gitlab-ci.yml) which can be invoked at any time. ## Update an old Docker image with new upstream docs content @@ -55,10 +55,10 @@ The website keeps changing and being improved. In order to consolidate those changes to the stable branches, we'd need to pick certain changes from time to time. -If this is not possible or there are many changes, merge master into them: +If this is not possible or there are many changes, merge main into them: ```shell git branch 12.0 -git fetch origin master -git merge origin/master +git fetch origin main +git merge origin/main ``` diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 7175a9f1a5c..aeaf12e23d1 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -23,7 +23,7 @@ Global navigation (the left-most pane in our three pane documentation) provides: ## Adding new items To add a topic to the global nav, edit -[`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/navigation.yaml) +[`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) and add your item. All new pages need a new navigation item. Without a navigation, the page becomes "orphaned". That @@ -109,7 +109,7 @@ the data among the nav in containers properly [styled](#css-classes). ### Data file The data file describes the structure of the navigation for the applicable project. -It is stored at <https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/navigation.yaml> +It is stored at <https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml> and comprises of three main components: - Sections @@ -267,19 +267,19 @@ Examples of relative URLs: ### Layout file (logic) -The [layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/global_nav.html) +The [layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/global_nav.html) is fed by the [data file](#data-file), builds the global nav, and is rendered by the -[default](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/default.html) layout. +[default](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/default.html) layout. The global nav contains links from all [four upstream projects](index.md#architecture). The [global nav URL](#urls) has a different prefix depending on the documentation file you change. -| Repository | Link prefix | Final URL | -|----------------------------------------------------------------|-------------|-----------| -| <https://gitlab.com/gitlab-org/gitlab/tree/master/doc> | `ee/` |`https://docs.gitlab.com/ee/` | -| <https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc> | `omnibus/` |`https://docs.gitlab.com/omnibus/` | -| <https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs> | `runner/` |`https://docs.gitlab.com/runner/` | -| <https://gitlab.com/charts/gitlab/tree/master/doc> | `charts/` |`https://docs.gitlab.com/charts/` | +| Repository | Link prefix | Final URL | +|----------------------------------------------------------------|-------------|------------------------------------| +| <https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc> | `ee/` | `https://docs.gitlab.com/ee/` | +| <https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc> | `omnibus/` | `https://docs.gitlab.com/omnibus/` | +| <https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs> | `runner/` | `https://docs.gitlab.com/runner/` | +| <https://gitlab.com/charts/gitlab/tree/master/doc> | `charts/` | `https://docs.gitlab.com/charts/` | ### CSS classes diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 35e9ab5157b..d410d77a1a0 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -49,9 +49,9 @@ GitLab docs content isn't kept in the `gitlab-docs` repository. All documentation files are hosted in the respective repository of each product, and all together are pulled to generate the docs website: -- [GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) +- [GitLab](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) - [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) -- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) +- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) NOTE: @@ -114,7 +114,7 @@ located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs If you need to rebuild the Docker images immediately (must have maintainer level permissions): WARNING: -If you change the Dockerfile configuration and rebuild the images, you can break the master +If you change the Dockerfile configuration and rebuild the images, you can break the main pipeline in the main `gitlab` repository as well as in `gitlab-docs`. Create an image with a different name first and test it to ensure you do not break the pipelines. @@ -132,7 +132,7 @@ a different name first and test it to ensure you do not break the pipelines. ### Deploy the docs site Every four hours a scheduled pipeline builds and deploys the docs site. The pipeline -fetches the current docs from the main project's master branch, builds it with Nanoc +fetches the current docs from the main project's main branch, builds it with Nanoc and deploys it to <https://docs.gitlab.com>. If you need to build and deploy the site immediately (must have maintainer level permissions): @@ -196,11 +196,11 @@ The links pointing to the files should be similar to: ``` Nanoc then builds and renders those links correctly according with what's -defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/Rules). +defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/Rules). ## Linking to source files -A helper called [`edit_on_gitlab`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/lib/helpers/edit_on_gitlab.rb) can be used +A helper called [`edit_on_gitlab`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/lib/helpers/edit_on_gitlab.rb) can be used to link to a page's source file. We can link to both the simple editor and the web IDE. Here's how you can use it in a Nanoc layout: @@ -223,9 +223,9 @@ for its search function. This is how it works: every 24h and [stores](https://community.algolia.com/docsearch/inside-the-engine.html) the [DocSearch index](https://community.algolia.com/docsearch/how-do-we-build-an-index.html) on [Algolia's servers](https://community.algolia.com/docsearch/faq.html#where-is-my-data-hosted%3F). -1. On the docs side, we use a [DocSearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/docsearch.html) which +1. On the docs side, we use a [DocSearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/docsearch.html) which is present on pretty much every page except <https://docs.gitlab.com/search/>, - which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/instantsearch.html). In those layouts, + which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/instantsearch.html). In those layouts, there's a JavaScript snippet which initiates DocSearch by using an API key and an index name (`gitlab`) that are needed for Algolia to show the results. diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index 9329b93bb26..46c74335932 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -1,5 +1,6 @@ --- redirect_to: 'https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases' +remove_date: '2021-07-12' --- This file was moved to [another location](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases). diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 67bdbffa2a1..871fb26ce08 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -109,7 +109,7 @@ Create an issue when you want to track bugs or future work. Prerequisites: -- A minimum of Contributor access to a project in GitLab. +- You must have at least the Developer role for a project. To create an issue: diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 0ac393a8509..225db273cb6 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -15,12 +15,13 @@ use the `#docs-processes` channel. In addition to this page, the following resources can help you craft and contribute to documentation: - [Doc contribution guidelines](../index.md) +- [A-Z word list](word_list.md) - [Doc style and consistency testing](../testing.md) - [UI text guidelines](https://design.gitlab.com/content/error-messages/) - [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) - [Google Developer Documentation Style Guide](https://developers.google.com/style) -- [Recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix) +- [Recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix) ## Documentation is the single source of truth (SSOT) @@ -305,13 +306,6 @@ GitLab documentation should be clear and easy to understand. - Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) - Use [inclusive language](#inclusive-language). -### Trademark - -Only use the GitLab name and trademarks in accordance with -[GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/brand-guidelines/#trademark). - -Don't use the possessive form of the word GitLab (`GitLab's`). - ### Capitalization #### Headings @@ -371,7 +365,7 @@ Capitalize names of: - Methods or methodologies. For example, Continuous Integration, Continuous Deployment, Scrum, and Agile. -Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) +Follow the capitalization style listed at the authoritative source for the entity, which may use non-standard case styles. For example: GitLab and npm. @@ -499,39 +493,6 @@ You can use these fake tokens as examples: | Health check token | `Tu7BgjR9qeZTEyRzGG2P` | | Request profile token | `7VgpS4Ax5utVD2esNstz` | -### Usage list -<!-- vale off --> - -| Usage | Guidance | -|-----------------------|----------| -| above | Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. | -| admin, admin area | Use **administration**, **administrator**, **administer**, or **Admin Area** instead. ([Vale](../testing.md#vale) rule: [`Admin.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Admin.yml)) | -| allow, enable | Try to avoid, unless you are talking about security-related features. For example, instead of "This feature allows you to create a pipeline," use "Use this feature to create a pipeline." This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). | -| and/or | Use **or** instead, or another sensible construction. | -| below | Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. | -| currently | Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) | -| easily | Do not use. If the user doesn't find the process to be these things, we lose their trust. | -| e.g. | Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | -| future tense | When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) | -| handy | Do not use. If the user doesn't find the process to be these things, we lose their trust. | -| high availability, HA | Do not use. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. | -| I | Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) | -| i.e. | Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | -| jargon | Do not use. Define the term or [link to a definition](#links-to-external-documentation). | -| may, might | **Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. | -| me, myself, mine | Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) | -| please | Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). | -| profanity | Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). | -| scalability | Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. | -| simply | Do not use. If the user doesn't find the process to be these things, we lose their trust. | -| slashes | Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed. | -| subgroup | Use instead of `sub-group`. | -| that | Do not use. Example: `the file that you save` can be `the file you save`. | -| useful | Do not use. If the user doesn't find the process to be these things, we lose their trust. | -| utilize | Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. | -| via | Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | - -<!-- vale on --> ### Contractions Contractions are encouraged, and can create a friendly and informal tone, @@ -540,7 +501,7 @@ especially in tutorials, instructional documentation, and Some contractions, however, should be avoided: -- Do not use [the word GitLab in a contraction](#trademark). +- Do not use the word "GitLab" in a contraction. - Do not use contractions with a proper noun and a verb. For example: @@ -1108,36 +1069,42 @@ document to ensure it links to the most recent version of the file. ## Navigation -When documenting navigation through the user interface: - -- Use the exact wording as shown in the UI, including any capital letters as-is. -- Use bold text for navigation items. +When documenting navigation through the user interface, use these terms and styles. ### What to call the menus Use these terms when referring to the main GitLab user interface elements: -- **Top menu**: This is the top menu that spans the width of the user interface. - It includes the GitLab logo, search field, counters, and the user's avatar. +- **Top bar**: This is the top bar that spans the width of the user interface. + It includes the menu, the GitLab logo, search field, counters, and the user's avatar. - **Left sidebar**: This is the navigation sidebar on the left of the user interface, specific to the project or group. - **Right sidebar**: This is the navigation sidebar on the right of the user interface, specific to the open issue, merge request, or epic. -### How to document the left sidebar +### How to document the menus -To be consistent, use this format when you refer to the left sidebar. +To be consistent, use this format when you write about UI navigation. -- Go to your project and select **Settings > CI/CD**. -- Go to your group and select **Settings > CI/CD**. -- Go to the Admin Area (**{admin}**) and select **Overview > Projects**. +1. On the top bar, select **Menu > Project** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. -For expandable menus, use this format: +Another example: -1. Go to your group and select **Settings > CI/CD**. +1. On the top bar, select **Menu > Group** and find your group. +1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. +An Admin Area example: + +`1. On the top bar, select **Menu >** **{admin}** **Admin**.` + +This text generates this HTML: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. + ## Images Images, including screenshots, can help a reader better understand a concept. @@ -1309,7 +1276,7 @@ hidden on the documentation site, but is displayed by `/help`. ## Code blocks - Always wrap code added to a sentence in inline code blocks (`` ` ``). - For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`. + For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [main]`. File names, commands, entries, and anything that refers to code should be added to code blocks. To make things easier for the user, always add a full code block for things that can be useful to copy and paste, as they can do it @@ -1416,10 +1383,10 @@ readability of the text. For example, this Markdown adds little to the accompanying text: ```markdown -1. Go to **{home}** **Project overview > Details**. +1. Go to **{home}** **Project information > Details**. ``` -1. Go to **{home}** **Project overview > Details**. +1. Go to **{home}** **Project information > Details**. However, these tables might help the reader connect the text to the user interface: diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md new file mode 100644 index 00000000000..fd8766bbfb6 --- /dev/null +++ b/doc/development/documentation/styleguide/word_list.md @@ -0,0 +1,163 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' +--- + +# A-Z word list + +To help ensure consistency in the documentation, follow this guidance. + +<!-- vale off --> +<!-- markdownlint-disable --> + +## above + +Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. + +## admin, admin area + +Use **administration**, **administrator**, **administer**, or **Admin Area** instead. ([Vale](../testing.md#vale) rule: [`Admin.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Admin.yml)) + +## allow, enable + +Try to avoid, unless you are talking about security-related features. For example, instead of "This feature allows you to create a pipeline," use "Use this feature to create a pipeline." This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). + +## and/or + +Instead of **and/or**, use or or rewrite the sentence to spell out both options. + +## below + +Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. + +## currently + +Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) + +## Developer + +When writing about the Developer role, use a capital "D." Do not use the phrase, "if you are a developer" +to mean someone who is assigned the Developer role. Instead, write it out. "If you are assigned the Developer role..." + +Do not use "Developer permissions." A user who is assigned the Developer role has a set of associated permissions. + +## easily + +Do not use. If the user doesn't find the process to be these things, we lose their trust. + +## e.g. + +Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) + +## future tense + +When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) + +## GitLab + +Do not make possessive (GitLab's). This guidance follows [GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/brand-guidelines/#trademark). + +## Guest + +When writing about the Guest role, use a capital "G." Do not use the phrase, "if you are a guest" +to mean someone who is assigned the Guest role. Instead, write it out. "If you are assigned the Guest role..." + +Do not use "Guest permissions." A user who is assigned the Guest role has a set of associated permissions. + +## handy + +Do not use. If the user doesn't find the process to be these things, we lose their trust. + +## high availability, HA + +Do not use. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. + +## I + +Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) + +## i.e. + +Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) + +## Maintainer + +When writing about the Maintainer role, use a capital "M." Do not use the phrase, "if you are a maintainer" +to mean someone who is assigned the Maintainer role. Instead, write it out. "If you are assigned the Maintainer role..." + +Do not use "Maintainer permissions." A user who is assigned the Maintainer role has a set of associated permissions. + +## may, might + +**Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. + +## me, myself, mine + +Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) + +## Owner + +When writing about the Owner role, use a capital "M." Do not use the phrase, "if you are an owner" +to mean someone who is assigned the Owner role. Instead, write it out. "If you are assigned the Owner role..." + +Do not use "Owner permissions." A user who is assigned the Owner role has a set of associated permissions. + +## permissions + +Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. + +## please + +Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). + +## profanity + +Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). + +## Reporter + +When writing about the Reporter role, use a capital "R." Do not use the phrase, "if you are a reporter" +to mean someone who is assigned the Reporter role. Instead, write it out. "If you are assigned the Reporter role..." + +Do not use "Reporter permissions." A user who is assigned the Reporter role has a set of associated permissions. + +## roles + +Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. + +## scalability + +Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. + +## simply + +Do not use. If the user doesn't find the process to be these things, we lose their trust. + +## slashes + +Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed. + +## subgroup + +Use instead of `sub-group`. + +## that + +Do not use. Example: `the file that you save` can be `the file you save`. + +## useful + +Do not use. If the user doesn't find the process to be these things, we lose their trust. + +## utilize + +Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. + +## via + +Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) + +<!-- vale on --> +<!-- markdownlint-enable --> diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index af95f3b9023..b634e2b93db 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -20,7 +20,7 @@ For the specifics of each test run in our CI/CD pipelines, see the configuration in the relevant projects: - <https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml> -- <https://gitlab.com/gitlab-org/gitlab-runner/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml> +- <https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/.gitlab/ci/docs.gitlab-ci.yml> - <https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/gitlab-ci-config/gitlab-com.yml> - <https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.gitlab-ci.yml> @@ -44,7 +44,7 @@ To run tests locally, it's important to: ### Lint checks -Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) +Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh) script and can be executed as follows: 1. Navigate to the `gitlab` directory. @@ -168,7 +168,7 @@ You can use markdownlint: [Vale](https://docs.errata.ai/vale/about/) is a grammar, style, and word usage linter for the English language. Vale's configuration is stored in the -[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root +[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) file located in the root directory of projects. Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of @@ -178,7 +178,7 @@ documentation directory of projects. You can find Vale configuration in the following projects: - [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs/.vale/gitlab) - [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) - [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) - [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) @@ -222,7 +222,7 @@ build pipelines: ``` We recommend installing the version of `markdownlint-cli` - [used](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L447) when building + [used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) when building the `image:docs-lint-markdown`. 1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using @@ -240,7 +240,7 @@ It's important to use linter versions that are the same or newer than those run CI/CD. This provides access to new features and possible bug fixes. To match the versions of `markdownlint-cli` and `vale` used in the GitLab projects, refer to the -[versions used](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L447) +[versions used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD. | Tool | Version | Command | Additional information | @@ -273,7 +273,7 @@ To configure Vale in your editor, install one of the following as appropriate: - Select the **Use CLI** checkbox. - In the <!-- vale gitlab.Spelling = NO --> **Config** setting, enter an absolute - path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) + path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) in one of the cloned GitLab repositories on your computer. <!-- vale gitlab.Spelling = YES --> @@ -330,7 +330,18 @@ document: - To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a `<!-- vale on -->` tag after the text. -Whenever possible, exclude only the problematic rule and line(s). +Whenever possible, exclude only the problematic rule and lines. For more information, see [Vale's documentation](https://docs.errata.ai/vale/scoping#markup-based-configuration). + +### Disable markdownlint tests + +To disable all markdownlint rules, add a `<!-- markdownlint-disable -->` tag before the text, and a +`<!-- markdownlint-enable -->` tag after the text. + +To disable only a [specific rule](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#rules), +add the rule number to the tag, for example `<!-- markdownlint-disable MD044 -->` +and `<!-- markdownlint-enable MD044 -->`. + +Whenever possible, exclude only the problematic lines. diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 8e2028532e4..f035b4d0888 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -85,8 +85,8 @@ If you are a member of the GitLab Slack workspace, you can request help in `#doc ### Reviewing and merging -Anyone with Maintainer access to the relevant GitLab project can merge documentation changes. -Maintainers must make a good-faith effort to ensure that the content: +Anyone with the [Maintainer role](../../user/permissions.md) to the relevant GitLab project can +merge documentation changes. Maintainers must make a good-faith effort to ensure that the content: - Is clear and sufficiently easy for the intended audience to navigate and understand. - Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide/index.md). @@ -115,7 +115,7 @@ The process involves the following: and link it from the merge request. The process is reflected in the **Documentation** -[merge request template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/merge_request_templates/Documentation.md). +[merge request template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation.md). ## Other ways to help diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 452b957c705..fb00fe748d0 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -30,7 +30,7 @@ should be added for EE. Licensed features can be stubbed using the spec helper `stub_licensed_features` in `EE::LicenseHelpers`. You can force GitLab to act as CE by either deleting the `ee/` directory or by -setting the [`FOSS_ONLY` environment variable](https://gitlab.com/gitlab-org/gitlab/blob/master/config/helpers/is_ee_env.js) +setting the [`FOSS_ONLY` environment variable](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/helpers/is_ee_env.js) to something that evaluates as `true`. The same works for running tests (for example `FOSS_ONLY=1 yarn jest`). @@ -71,7 +71,7 @@ is applied not only to models. Here's a list of other examples: - `ee/app/views/foo/_bar.html.haml` This works because for every path that is present in CE's eager-load/auto-load -paths, we add the same `ee/`-prepended path in [`config/application.rb`](https://gitlab.com/gitlab-org/gitlab/blob/925d3d4ebc7a2c72964ce97623ae41b8af12538d/config/application.rb#L42-52). +paths, we add the same `ee/`-prepended path in [`config/application.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/925d3d4ebc7a2c72964ce97623ae41b8af12538d/config/application.rb#L42-52). This also applies to views. #### Testing EE-only features @@ -538,7 +538,7 @@ In this case, we could as well just use `render_ce` which would ignore any EE partials. One example would be `ee/app/views/shared/issuable/form/_default_templates.html.haml`: -``` haml +```haml - if @project.feature_available?(:issuable_default_templates) = render_ce 'shared/issuable/form/default_templates' - elsif show_promotions? diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 6b829faf74d..d5f6e95033f 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -36,15 +36,15 @@ Additionally, if you need large repositories or multiple forks for testing, plea ## How does it work? -The Elasticsearch integration depends on an external indexer. We ship an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). The user must trigger the initial indexing via a Rake task but, after this is done, GitLab itself will trigger reindexing when required via `after_` callbacks on create, update, and destroy that are inherited from [`/ee/app/models/concerns/elastic/application_versioned_search.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/models/concerns/elastic/application_versioned_search.rb). +The Elasticsearch integration depends on an external indexer. We ship an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). The user must trigger the initial indexing via a Rake task but, after this is done, GitLab itself will trigger reindexing when required via `after_` callbacks on create, update, and destroy that are inherited from [`/ee/app/models/concerns/elastic/application_versioned_search.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/concerns/elastic/application_versioned_search.rb). After initial indexing is complete, create, update, and delete operations for all models except projects (see [#207494](https://gitlab.com/gitlab-org/gitlab/-/issues/207494)) are tracked in a Redis [`ZSET`](https://redis.io/topics/data-types#sorted-sets). A regular `sidekiq-cron` `ElasticIndexBulkCronWorker` processes this queue, updating many Elasticsearch documents at a time with the [Bulk Request API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html). -Search queries are generated by the concerns found in [`ee/app/models/concerns/elastic`](https://gitlab.com/gitlab-org/gitlab/tree/master/ee/app/models/concerns/elastic). These concerns are also in charge of access control, and have been a historic source of security bugs so please pay close attention to them! +Search queries are generated by the concerns found in [`ee/app/models/concerns/elastic`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/app/models/concerns/elastic). These concerns are also in charge of access control, and have been a historic source of security bugs so please pay close attention to them! ## Existing Analyzers/Tokenizers/Filters -These are all defined in [`ee/lib/elastic/latest/config.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/elastic/latest/config.rb) +These are all defined in [`ee/lib/elastic/latest/config.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/elastic/latest/config.rb) ### Analyzers @@ -214,7 +214,7 @@ end ``` Applied migrations are stored in `gitlab-#{RAILS_ENV}-migrations` index. All migrations not executed -are applied by the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/workers/elastic/migration_worker.rb) +are applied by the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/workers/elastic/migration_worker.rb) cron worker sequentially. To update Elastic index mappings, apply the configuration to the respective files: @@ -227,15 +227,15 @@ Any data or index cleanup needed to support migration retries should be handled ### Migration options supported by the `Elastic::MigrationWorker` -[`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/workers/elastic/migration_worker.rb) supports the following migration options: +[`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/workers/elastic/migration_worker.rb) supports the following migration options: -- `batched!` - Allow the migration to run in batches. If set, the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/workers/elastic/migration_worker.rb) +- `batched!` - Allow the migration to run in batches. If set, the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/workers/elastic/migration_worker.rb) will re-enqueue itself with a delay which is set using the `throttle_delay` option described below. The batching must be handled within the `migrate` method, this setting controls the re-enqueuing only. - `throttle_delay` - Sets the wait time in between batch runs. This time should be set high enough to allow each migration batch enough time to finish. Additionally, the time should be less than 30 minutes since that is how often the -[`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/workers/elastic/migration_worker.rb) +[`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/workers/elastic/migration_worker.rb) cron worker runs. Default value is 5 minutes. - `pause_indexing!` - Pause indexing while the migration runs. This setting will record the indexing setting before @@ -308,12 +308,15 @@ We choose to use GitLab major version upgrades as a safe time to remove backwards compatibility for indices that have not been fully migrated. We [document this in our upgrade documentation](../update/index.md#upgrading-to-a-new-major-version). We also -choose to remove the migration code and tests so that: +choose to replace the migration code with the halted migration +and remove tests so that: - We don't need to maintain any code that is called from our Advanced Search migrations. - We don't waste CI time running tests for migrations that we don't support anymore. +- Operators who have not run this migration and who upgrade directly to the + target version will see a message prompting them to reindex from scratch. To be extra safe, we will not delete migrations that were created in the last minor version before the major upgrade. So, if we are upgrading to `%14.0`, @@ -334,18 +337,10 @@ For every migration that was created 2 minor versions before the major version being upgraded to, we do the following: 1. Confirm the migration has actually completed successfully for GitLab.com. -1. Replace the content of `migrate` and `completed?` methods as follows: +1. Replace the content of the migration with: ```ruby - def migrate - log_raise "Migration has been deleted in the last major version upgrade." \ - "Migrations are supposed to be finished before upgrading major version https://docs.gitlab.com/ee/update/#upgrading-to-a-new-major-version ." \ - "To correct this issue, recreate your index from scratch: https://docs.gitlab.com/ee/integration/elasticsearch.html#last-resort-to-recreate-an-index." - end - - def completed? - false - end + include Elastic::MigrationObsolete ``` 1. Delete any spec files to support this migration. diff --git a/doc/development/event_tracking/backend.md b/doc/development/event_tracking/backend.md index e8b8e0c4885..3931f0b35ab 100644 --- a/doc/development/event_tracking/backend.md +++ b/doc/development/event_tracking/backend.md @@ -1,8 +1,9 @@ --- redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-guide/' +remove_date: '2021-12-01' --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). -<!-- This redirect file can be deleted after December 1, 2021. --> +<!-- This redirect file can be deleted after 2021-12-01. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/event_tracking/frontend.md b/doc/development/event_tracking/frontend.md index e8b8e0c4885..3931f0b35ab 100644 --- a/doc/development/event_tracking/frontend.md +++ b/doc/development/event_tracking/frontend.md @@ -1,8 +1,9 @@ --- redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-guide/' +remove_date: '2021-12-01' --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). -<!-- This redirect file can be deleted after December 1, 2021. --> +<!-- This redirect file can be deleted after 2021-12-01. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/event_tracking/index.md b/doc/development/event_tracking/index.md index e8b8e0c4885..3931f0b35ab 100644 --- a/doc/development/event_tracking/index.md +++ b/doc/development/event_tracking/index.md @@ -1,8 +1,9 @@ --- redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-guide/' +remove_date: '2021-12-01' --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). -<!-- This redirect file can be deleted after December 1, 2021. --> +<!-- This redirect file can be deleted after 2021-12-01. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/experiment_guide/experimentation.md b/doc/development/experiment_guide/experimentation.md index 7135f8acd9b..ee0f63342f1 100644 --- a/doc/development/experiment_guide/experimentation.md +++ b/doc/development/experiment_guide/experimentation.md @@ -6,10 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create an A/B test with `Experimentation Module` +NOTE: +We recommend using [GLEX](gitlab_experiment.md) for new experiments. + ## Implement the experiment 1. Add the experiment to the `Gitlab::Experimentation::EXPERIMENTS` hash in - [`experimentation.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib%2Fgitlab%2Fexperimentation.rb): + [`experimentation.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib%2Fgitlab%2Fexperimentation.rb): ```ruby EXPERIMENTS = { diff --git a/doc/development/experiment_guide/gitlab_experiment.md b/doc/development/experiment_guide/gitlab_experiment.md index db9bc521cfd..820d1da0080 100644 --- a/doc/development/experiment_guide/gitlab_experiment.md +++ b/doc/development/experiment_guide/gitlab_experiment.md @@ -394,6 +394,26 @@ You may be asked from time to time to track a specific record ID in experiments. The approach is largely up to the PM and engineer creating the implementation. No recommendations are provided here at this time. +### Record experiment subjects + +Snowplow tracking of identifiable users or groups is prohibited, but you can still +determine if an experiment is successful or not. We're allowed to record the ID of +a namespace, project or user in our database. Therefore, we can tell the experiment +to record their ID together with the assigned experiment variant in the +`experiment_subjects` database table for later analysis. + +For the recording to work, the experiment's context must include a `namespace`, +`group`, `project`, `user`, or `actor`. + +To record the experiment subject when you first assign a variant, call `record!` in +the experiment's block: + +```ruby +experiment(:pill_color, actor: current_user) do |e| + e.record! +end +``` + ## Test with RSpec This gem provides some RSpec helpers and custom matchers. These are in flux as of GitLab 13.10. diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 0d534a974a1..798c6ff84d0 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -12,7 +12,7 @@ Experiments are run as an A/B/n test, and are behind a feature flag to turn the ## Experiment tracking issue -Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. The tracking issue is similar to a feature flag rollout issue, and is also used to track the status of an experiment. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). +Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. The tracking issue is similar to a feature flag rollout issue, and is also used to track the status of an experiment. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). After the deadline, the issue needs to be resolved and either: - It was successful and the experiment becomes the new default. @@ -46,17 +46,25 @@ One is built into GitLab directly and has been around for a while (this is calle to as `Gitlab::Experiment` -- GLEX for short. Both approaches use [experiment](../feature_flags/index.md#experiment-type) -feature flags, and there is currently no strong suggestion to use one over the other. +feature flags. We recommend using GLEX rather than `Experimentation Module` for new experiments. -| Feature | `Experimentation Module` | GLEX | -| -------------------- |------------------------- | ---- | -| Record user grouping | Yes | No | -| Uses feature flags | Yes | Yes | -| Multivariate (A/B/n) | No | Yes | - -- [Implementing an A/B experiment using `Experimentation Module`](experimentation.md) - [Implementing an A/B/n experiment using GLEX](gitlab_experiment.md) +- [Implementing an A/B experiment using `Experimentation Module`](experimentation.md) Historical Context: `Experimentation Module` was built iteratively with the needs that appeared while implementing Growth sub-department experiments, while GLEX was built with the findings of the team and an easier to use API. + +### Add new icons and illustrations for experiments + +Some experiments may require you to add custom icons or illustrations to our codebase. +This process is lengthy and at this stage, the outcome of the experiment uncertain. +Therefore, you should postpone this effort until the [experiment cleanup process](https://about.gitlab.com/handbook/engineering/development/growth/#experiment-cleanup-issue). + +We recommend the following workflow: + +1. Add an icon or illustration as an `.svg` file in the `/app/assets/images` (or EE) path in the GitLab repository. +1. Use `image_tag` or `image_path` to render it via the asset pipeline. +1. **If the experiment is a success**, designers add the new icon or illustration to the Pajamas UI kit as part of the cleanup process. + Engineers can then add it to the [SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) and modify the implementation based on the + [Frontend Development Guidelines](../fe_guide/icons.md#usage-in-hamlrails-2). diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index ab1325c67a9..15818941b24 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.md @@ -39,9 +39,20 @@ so when in doubt don't use `aria-*`, `role`, and `tabindex` and stick with seman - [Clickable icons](#icons-that-are-clickable) are buttons, that is, `<gl-button icon="close" />` is used and not `<gl-icon />`. - Icon-only buttons have an `aria-label`. - Interactive elements can be [accessed with the Tab key](#support-keyboard-only-use) and have a visible focus state. +- Elements with [tooltips](#tooltips) are focusable using the Tab key. - Are any `role`, `tabindex` or `aria-*` attributes unnecessary? - Can any `div` or `span` elements be replaced with a more semantic [HTML element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) like `p`, `button`, or `time`? +## Provide a good document outline + +[Headings are the primary mechanism used by screen reader users to navigate content](https://webaim.org/projects/screenreadersurvey8/#finding). +Therefore, the structure of headings on a page should make sense, like a good table of contents. +We should ensure that: + +- There is only one `h1` element on the page. +- Heading levels are not skipped. +- Heading levels are nested correctly. + ## Provide accessible names for screen readers To provide markup with accessible names, ensure every: @@ -257,6 +268,9 @@ Image examples: <!-- SVGs implicitly have a graphics role so if it is semantically an image we should apply `role="img"` --> <svg role="img" :alt="__('A description of the image')" /> + +<!-- A decorative image, hidden from screen readers --> +<img :src="imagePath" :alt="" /> ``` #### Buttons and links with descriptive accessible names @@ -275,6 +289,14 @@ Buttons and links should have accessible names that are descriptive enough to be <gl-link :href="url">{{ __("GitLab's accessibility page") }}</gl-link> ``` +#### Links styled like buttons + +Links can be styled like buttons using `GlButton`. + +```html + <gl-button :href="url">{{ __('Link styled as a button') }}</gl-button> +``` + ## Role In general, avoid using `role`. @@ -336,7 +358,7 @@ Once the markup is semantically complete, use CSS to update it to its desired vi <div role="button" tabindex="0" @click="expand">Expand</div> <!-- good --> -<gl-button @click="expand">Expand</gl-button> +<gl-button class="gl-p-0!" category="tertiary" @click="expand">Expand</gl-button> ``` ### Do not use `tabindex="0"` on interactive elements @@ -423,6 +445,30 @@ Icons that are clickable are semantically buttons, so they should be rendered as <gl-button icon="close" category="tertiary" :aria-label="__('Close')" @click="handleClick" /> ``` +## Tooltips + +When adding tooltips, we must ensure that the element with the tooltip can receive focus so keyboard users can see the tooltip. +If the element is a static one, such as an icon, we can enclose it in a button, which already is +focusable, so we don't have to add `tabindex=0` to the icon. + +The following code snippet is a good example of an icon with a tooltip. + +- It is automatically focusable, as it is a button. +- It is given an accessible name with `aria-label`, as it is a button with no text. +- We can use the `gl-hover-bg-transparent!` class if we don't want the button's background to become gray on hover. +- We can use the `gl-p-0!` class to remove the button padding, if needed. + +```html +<gl-button + v-gl-tooltip + class="gl-hover-bg-transparent! gl-p-0!" + icon="warning" + category="tertiary" + :title="tooltipText" + :aria-label="__('Warning')" +/> +``` + ## Hiding elements Use the following table to hide elements from users, when appropriate. @@ -478,5 +524,3 @@ We have two options for Web accessibility testing: - [The A11Y Project](https://www.a11yproject.com/) is a good resource for accessibility - [Awesome Accessibility](https://github.com/brunopulis/awesome-a11y) is a compilation of accessibility-related material -- You can read [Chrome Accessibility Developer Tools'](https://github.com/GoogleChrome/accessibility-developer-tools) - rules on its [Audit Rules page](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules) diff --git a/doc/development/fe_guide/content_editor.md b/doc/development/fe_guide/content_editor.md new file mode 100644 index 00000000000..f6329f39636 --- /dev/null +++ b/doc/development/fe_guide/content_editor.md @@ -0,0 +1,116 @@ +--- +stage: Create +group: Editor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Content Editor **(FREE)** + +The Content Editor is a UI component that provides a WYSIWYG editing +experience for [GitLab Flavored Markdown](../../user/markdown.md) (GFM) in the GitLab application. +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://www.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. + +## Architecture remarks + +At a high level, the Content Editor: + +- Imports arbitrary Markdown. +- Renders it in a HTML editing area. +- Exports it back to Markdown with changes introduced by the user. + +The Content Editor relies on the +[Markdown API endpoint](../../api/markdown.md) to transform Markdown +into HTML. It sends the Markdown input to the REST API and displays the API's +HTML output in the editing area. The editor exports the content back to Markdown +using a client-side library that serializes editable documents into Markdown. + + + +Check the [Content Editor technical design document](https://docs.google.com/document/d/1fKOiWpdHned4KOLVOOFYVvX1euEjMP5rTntUhpapdBg) +for more information about the design decisions that drive the development of the editor. + +**NOTE**: We also designed the Content Editor to be extensible. We intend to provide +more information about extension development for supporting new types of content in upcoming +milestones. + +## GitLab Flavored Markdown support + +The [GitLab Flavored Markdown](../../user/markdown.md) extends +the [CommonMark specification](https://spec.commonmark.org/0.29/) with support for a +variety of content types like diagrams, math expressions, and tables. Supporting +all GitLab Flavored Markdown content types in the Content Editor is a work in progress. For +the status of the ongoing development for CommonMark and GitLab Flavored Markdown support, read: + +- [Basic Markdown formatting extensions](https://gitlab.com/groups/gitlab-org/-/epics/5404) epic. +- [GitLab Flavored Markdown extensions](https://gitlab.com/groups/gitlab-org/-/epics/5438) epic. + +## Usage + +To include the Content Editor in your feature, import the `createContentEditor` factory +function and the `ContentEditor` Vue component. `createContentEditor` sets up an instance +of [tiptap's Editor class](https://www.tiptap.dev/api/editor) with all the necessary +extensions to support editing GitLab Flavored Markdown content. It also creates +a Markdown serializer that allows exporting tiptap's document format to Markdown. + +`createContentEditor` requires a `renderMarkdown` parameter invoked +by the editor every time it needs to convert Markdown to HTML. The Content Editor +does not provide a default value for this function yet. + +**NOTE**: The Content Editor is in an early development stage. Usage and development +guidelines are subject to breaking changes in the upcoming months. + +```html +<script> +import { GlButton } from '@gitlab/ui'; +import { createContentEditor, ContentEditor } from '~/content_editor'; +import { __ } from '~/locale'; +import createFlash from '~/flash'; + +export default { + components: { + ContentEditor, + GlButton, + }, + data() { + return { + contentEditor: null, + } + }, + created() { + this.contentEditor = createContentEditor({ + renderMarkdown: (markdown) => Api.markdown({ text: markdown }), + }); + + try { + await this.contentEditor.setSerializedContent(this.content); + } catch (e) { + createFlash(__('There was an error loading content in the editor'), e); + } + }, + methods: { + async save() { + await Api.updateContent({ + content: this.contentEditor.getSerializedContent(), + }); + }, + }, +}; +</script> +<template> + <div> + <content-editor :content-editor="contentEditor" /> + <gl-button @click="save()">Save</gl-button> + </div> +</template> +``` + +Call `setSerializedContent` to set initial Markdown in the Editor. This method is +asynchronous because it makes an API request to render the Markdown input. +`getSerializedContent` returns a Markdown string that represents the serialized +version of the editable document. diff --git a/doc/development/fe_guide/design_anti_patterns.md b/doc/development/fe_guide/design_anti_patterns.md index ee4fceff927..0788921fce4 100644 --- a/doc/development/fe_guide/design_anti_patterns.md +++ b/doc/development/fe_guide/design_anti_patterns.md @@ -119,8 +119,8 @@ Here are some ills that Singletons often produce: such as no clear ownership and no access control. These leads to high coupling situations that can be buggy and difficult to untangle. 1. **Infectious.** Singletons are infectious, especially when they manage state. Consider the component - [RepoEditor](https://gitlab.com/gitlab-org/gitlab/blob/27ad6cb7b76430fbcbaf850df68c338d6719ed2b/app%2Fassets%2Fjavascripts%2Fide%2Fcomponents%2Frepo_editor.vue#L0-1) - used in the Web IDE. This component interfaces with a Singleton [Editor](https://gitlab.com/gitlab-org/gitlab/blob/862ad57c44ec758ef3942ac2e7a2bd40a37a9c59/app%2Fassets%2Fjavascripts%2Fide%2Flib%2Feditor.js#L21) + [RepoEditor](https://gitlab.com/gitlab-org/gitlab/-/blob/27ad6cb7b76430fbcbaf850df68c338d6719ed2b/app%2Fassets%2Fjavascripts%2Fide%2Fcomponents%2Frepo_editor.vue#L0-1) + used in the Web IDE. This component interfaces with a Singleton [Editor](https://gitlab.com/gitlab-org/gitlab/-/blob/862ad57c44ec758ef3942ac2e7a2bd40a37a9c59/app%2Fassets%2Fjavascripts%2Fide%2Flib%2Feditor.js#L21) which manages some state for working with Monaco. Because of the Singleton nature of the Editor class, the component `RepoEditor` is now forced to be a Singleton as well. Multiple instances of this component would cause production issues because no one truly owns the instance of `Editor`. diff --git a/doc/development/fe_guide/editor_lite.md b/doc/development/fe_guide/editor_lite.md index 5ad0c753ced..f28588c23e9 100644 --- a/doc/development/fe_guide/editor_lite.md +++ b/doc/development/fe_guide/editor_lite.md @@ -15,6 +15,7 @@ GitLab features use it, including: - [CI Linter](../../ci/lint.md) - [Snippets](../../user/snippets.md) - [Web Editor](../../user/project/repository/web_editor.md) +- [Security Policies](../../user/application_security/threat_monitoring/index.md) ## How to use Editor Lite diff --git a/doc/development/fe_guide/event_tracking.md b/doc/development/fe_guide/event_tracking.md index e8b8e0c4885..3931f0b35ab 100644 --- a/doc/development/fe_guide/event_tracking.md +++ b/doc/development/fe_guide/event_tracking.md @@ -1,8 +1,9 @@ --- redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-guide/' +remove_date: '2021-12-01' --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). -<!-- This redirect file can be deleted after December 1, 2021. --> +<!-- This redirect file can be deleted after 2021-12-01. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index bf1dae6e7bd..6b9d5ace4e6 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.md @@ -32,15 +32,15 @@ question: document.body.dataset.page ``` -Find here the [source code setting the attribute](https://gitlab.com/gitlab-org/gitlab/blob/cc5095edfce2b4d4083a4fb1cdc7c0a1898b9921/app/views/layouts/application.html.haml#L4). +Find here the [source code setting the attribute](https://gitlab.com/gitlab-org/gitlab/-/blob/cc5095edfce2b4d4083a4fb1cdc7c0a1898b9921/app/views/layouts/application.html.haml#L4). #### Rails routes -The `rake routes` command can be used to list all the routes available in the application. Piping the output into `grep`, we can perform a search through the list of available routes. +The `rails routes` command can be used to list all the routes available in the application. Piping the output into `grep`, we can perform a search through the list of available routes. The output includes the request types available, route parameters and the relevant controller. ```shell -bundle exec rake routes | grep "issues" +bundle exec rails routes | grep "issues" ``` ### 2. `modal_copy_button` vs `clipboard_button` @@ -82,7 +82,7 @@ follow up issue and attach it to the component implementation epic found in the ### 4. My submit form button becomes disabled after submitting -A Submit button inside of a form attaches an `onSubmit` event listener on the form element. [This code](https://gitlab.com/gitlab-org/gitlab/blob/794c247a910e2759ce9b401356432a38a4535d49/app/assets/javascripts/main.js#L225) adds a `disabled` class selector to the submit button when the form is submitted. To avoid this behavior, add the class `js-no-auto-disable` to the button. +A Submit button inside of a form attaches an `onSubmit` event listener on the form element. [This code](https://gitlab.com/gitlab-org/gitlab/-/blob/794c247a910e2759ce9b401356432a38a4535d49/app/assets/javascripts/main.js#L225) adds a `disabled` class selector to the submit button when the form is submitted. To avoid this behavior, add the class `js-no-auto-disable` to the button. ### 5. Should one use a full URL (for example `gon.gitlab_url`) or a full path (for example `gon.relative_url_root`) when referencing backend endpoints? @@ -172,7 +172,7 @@ To return to the normal development mode: ### 8. Babel polyfills -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/28837) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28837) in GitLab 12.8. GitLab has enabled the Babel `preset-env` option [`useBuiltIns: 'usage'`](https://babeljs.io/docs/en/babel-preset-env#usebuiltins-usage). diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 49c511c2b85..870605c82f4 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -94,7 +94,7 @@ their execution by clicking **Execute query** button on the top left: ## Apollo Client To save duplicated clients getting created in different apps, we have a -[default client](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/javascripts/lib/graphql.js) that should be used. This sets up the +[default client](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/lib/graphql.js) that should be used. This sets up the Apollo client with the correct URL and also sets the CSRF headers. Default client accepts two parameters: `resolvers` and `config`. @@ -106,6 +106,12 @@ Default client accepts two parameters: `resolvers` and `config`. - `assumeImmutableResults` (set to `false` by default) - this setting, when set to `true`, assumes that every single operation on updating Apollo Cache is immutable. It also sets `freezeResults` to `true`, so any attempt on mutating Apollo Cache throws a console warning in development environment. Please ensure you're following the immutability pattern on cache update operations before setting this option to `true`. - `fetchPolicy` determines how you want your component to interact with the Apollo cache. Defaults to "cache-first". +### Multiple client queries for the same object + +If you are make multiple queries to the same Apollo client object you might encounter the following error: "Store error: the application attempted to write an object with no provided ID but the store already contains an ID of SomeEntity". [This error only should occur when you have made a query with an ID field for a portion, then made another that returns what would be the same object, but is missing the ID field.](https://github.com/apollographql/apollo-client/issues/2510#issue-271829009) + +Please note this is being tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326101) and the documentation will be updated when this issue is resolved. + ## GraphQL Queries To save query compilation at runtime, webpack can directly import `.graphql` @@ -1091,7 +1097,7 @@ it('renders a loading state', () => { const mockApollo = createMockApolloProvider(); const wrapper = createComponent({ mockApollo }); - expect(wrapper.find(LoadingSpinner).exists()).toBe(true) + expect(wrapper.findComponent(LoadingSpinner).exists()).toBe(true) }); it('renders designs list', async () => { @@ -1393,7 +1399,6 @@ describe('My Index test with `createMockApollo`', () => { afterEach(() => { wrapper.destroy(); - wrapper = null; fetchLocalUserSpy = null; }); diff --git a/doc/development/fe_guide/img/content_editor_highlevel_diagram.png b/doc/development/fe_guide/img/content_editor_highlevel_diagram.png Binary files differnew file mode 100644 index 00000000000..73a71cf5843 --- /dev/null +++ b/doc/development/fe_guide/img/content_editor_highlevel_diagram.png diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 0f3754c29e7..00f0d72571a 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -93,6 +93,11 @@ General information about frontend [dependencies](dependencies.md) and how we ma How we implement [keyboard shortcuts](keyboard_shortcuts.md) that can be customized and disabled. +## Editors + +GitLab text editing experiences are provided by the [Source Editor](editor_lite.md) and +the [Content Editor](content_editor.md). + ## Frontend FAQ Read the [frontend's FAQ](frontend_faq.md) for common small pieces of helpful information. diff --git a/doc/development/fe_guide/style/vue.md b/doc/development/fe_guide/style/vue.md index 93e4f234ccb..5c79d47e7b0 100644 --- a/doc/development/fe_guide/style/vue.md +++ b/doc/development/fe_guide/style/vue.md @@ -463,7 +463,7 @@ Creating a global, mutable wrapper provides a number of advantages, including th let wrapper; // this can now be reused across tests - const findMyComponent = wrapper.find(MyComponent); + const findMyComponent = wrapper.findComponent(MyComponent); // ... }) ``` @@ -565,16 +565,15 @@ the mounting function (`mount` or `shallowMount`) to be used to mount the compon function createComponent({ mountFn = shallowMount } = {}) { } ``` -1. Wrap calls to `mount` and `shallowMount` in `extendedWrapper`, this exposes `wrapper.findByTestId()`: +1. Use the `mountExtended` and `shallowMountExtended` helpers to expose `wrapper.findByTestId()`: ```javascript - import { shallowMount } from '@vue/test-utils'; - import { extendedWrapper } from 'helpers/vue_test_utils_helper'; + import { shallowMountExtended } from 'helpers/vue_test_utils_helper'; import { SomeComponent } from 'components/some_component.vue'; let wrapper; - const createWrapper = () => { wrapper = extendedWrapper(shallowMount(SomeComponent)); }; + const createWrapper = () => { wrapper = shallowMountExtended(SomeComponent); }; const someButton = () => wrapper.findByTestId('someButtonTestId'); ``` diff --git a/doc/development/fe_guide/troubleshooting.md b/doc/development/fe_guide/troubleshooting.md index 1b3991ee80d..028184e0397 100644 --- a/doc/development/fe_guide/troubleshooting.md +++ b/doc/development/fe_guide/troubleshooting.md @@ -27,15 +27,15 @@ See [this video](https://youtu.be/-BkEhghP-kM) for an in-depth overview and inve **Remedy - Try cloning the object that has Vue watchers** ```patch -- expect(wrapper.find(ChildComponent).props()).toEqual(...); -+ expect(cloneDeep(wrapper.find(ChildComponent).props())).toEqual(...) +- expect(wrapper.findComponent(ChildComponent).props()).toEqual(...); ++ expect(cloneDeep(wrapper.findComponent(ChildComponent).props())).toEqual(...) ``` **Remedy - Try using `toMatchObject` instead of `toEqual`** ```patch -- expect(wrapper.find(ChildComponent).props()).toEqual(...); -+ expect(wrapper.find(ChildComponent).props()).toMatchObject(...); +- expect(wrapper.findComponent(ChildComponent).props()).toEqual(...); ++ expect(wrapper.findComponent(ChildComponent).props()).toMatchObject(...); ``` Please note that `toMatchObject` actually changes the nature of the assertion and won't fail if some items are **missing** from the expectation. diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 1cce699218c..0a769f257d0 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -13,7 +13,7 @@ To get started with Vue, read through [their documentation](https://vuejs.org/v2 What is described in the following sections can be found in these examples: - [Web IDE](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/ide/stores) -- [Security products](https://gitlab.com/gitlab-org/gitlab/tree/master/ee/app/assets/javascripts/vue_shared/security_reports) +- [Security products](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/app/assets/javascripts/vue_shared/security_reports) - [Registry](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/registry/stores) ## Vue architecture @@ -323,17 +323,13 @@ testing the rendered output. Here's an example of a well structured unit test for [this Vue component](#appendix---vue-component-subject-under-test): ```javascript -import { shallowMount } from '@vue/test-utils'; -import { extendedWrapper } from 'helpers/vue_test_utils_helper'; import { GlLoadingIcon } from '@gitlab/ui'; import MockAdapter from 'axios-mock-adapter'; +import { shallowMountExtended } from 'helpers/vue_test_utils_helper'; import axios from '~/lib/utils/axios_utils'; import App from '~/todos/app.vue'; -const TEST_TODOS = [ - { text: 'Lorem ipsum test text' }, - { text: 'Lorem ipsum 2' }, -]; +const TEST_TODOS = [{ text: 'Lorem ipsum test text' }, { text: 'Lorem ipsum 2' }]; const TEST_NEW_TODO = 'New todo title'; const TEST_TODO_PATH = '/todos'; @@ -351,28 +347,27 @@ describe('~/todos/app.vue', () => { afterEach(() => { // IMPORTANT: Clean up the component instance and axios mock adapter wrapper.destroy(); - wrapper = null; - mock.restore(); }); // It is very helpful to separate setting up the component from // its collaborators (for example, Vuex and axios). const createWrapper = (props = {}) => { - wrapper = extendedWrapper( - shallowMount(App, { - propsData: { - path: TEST_TODO_PATH, - ...props, - }, - }) - ); + wrapper = shallowMountExtended(App, { + propsData: { + path: TEST_TODO_PATH, + ...props, + }, + }); }; // Helper methods greatly help test maintainability and readability. - const findLoader = () => wrapper.find(GlLoadingIcon); + const findLoader = () => wrapper.findComponent(GlLoadingIcon); const findAddButton = () => wrapper.findByTestId('add-button'); const findTextInput = () => wrapper.findByTestId('text-input'); - const findTodoData = () => wrapper.findAll('[data-testid="todo-item"]').wrappers.map(wrapper => ({ text: wrapper.text() })); + const findTodoData = () => + wrapper + .findAllByTestId('todo-item') + .wrappers.map((item) => ({ text: item.text() })); describe('when mounted and loading', () => { beforeEach(() => { @@ -401,14 +396,13 @@ describe('~/todos/app.vue', () => { expect(findTodoData()).toEqual(TEST_TODOS); }); - it('when todo is added, should post new todo', () => { - findTextInput().vm.$emit('update', TEST_NEW_TODO) + it('when todo is added, should post new todo', async () => { + findTextInput().vm.$emit('update', TEST_NEW_TODO); findAddButton().vm.$emit('click'); - return wrapper.vm.$nextTick() - .then(() => { - expect(mock.history.post.map(x => JSON.parse(x.data))).toEqual([{ text: TEST_NEW_TODO }]); - }); + await wrapper.vm.$nextTick(); + + expect(mock.history.post.map((x) => JSON.parse(x.data))).toEqual([{ text: TEST_NEW_TODO }]); }); }); }); diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index d44ab64ae5d..3d0044928f1 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -40,7 +40,7 @@ When using Vuex at GitLab, separate these concerns into different files to impro The following example shows an application that lists and adds users to the state. (For a more complex example implementation, review the security -applications stored in this [repository](https://gitlab.com/gitlab-org/gitlab/tree/master/ee/app/assets/javascripts/vue_shared/security_reports/store)). +applications stored in this [repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/app/assets/javascripts/vue_shared/security_reports/store)). ### `index.js` @@ -464,7 +464,6 @@ describe('component', () => { afterEach(() => { wrapper.destroy(); - wrapper = null; }); it('should show a user', async () => { diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index 08a4401181b..a9ebcfc9fba 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -99,7 +99,7 @@ Guidelines: Before toggling any feature flag, check that there are no ongoing significant incidents on GitLab.com. You can do this by checking the `#production` and `#incident-management` Slack channels, or looking for -[open incident issues](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=incident) +[open incident issues](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/?scope=all&state=opened&label_name[]=incident) (although check the dates and times). We do not want to introduce changes during an incident, as it can make @@ -213,9 +213,6 @@ actors. Feature.enabled?(:some_feature, group) ``` -**Percentage of time** rollout is not a good idea if what you want is to make sure a feature -is always on or off to the users. In that case, **Percentage of actors** rollout is a better method. - Lastly, to verify that the feature is deemed stable in as many cases as possible, you should fully roll out the feature by enabling the flag **globally** by running: @@ -226,6 +223,32 @@ you should fully roll out the feature by enabling the flag **globally** by runni This changes the feature flag state to be **enabled** always, which overrides the existing gates (e.g. `--group=gitlab-org`) in the above processes. +Note, that if an actor based feature gate is present, switching the +`default_enabled` attribute of the YAML definition from `false` to `true` +will not have any effect. The feature gate must be deleted first. + +For example, a feature flag is set via chatops: + +```shell +/chatops run feature set --project=gitlab-org/gitlab some_feature true +``` + +When the `default_enabled` attribute in the YAML definition is switched to +`true`, the feature gate must be deleted to have the desired effect: + +```shell +/chatops run feature delete some_feature +``` + +##### Percentage of actors vs percentage of time rollouts + +If you want to make sure a feature is always on or off for users, use a **Percentage of actors** +rollout. Avoid using percentage of _time_ rollouts in this case. + +A percentage of _time_ rollout can introduce inconsistent behavior when `Feature.enabled?` +is used multiple times in the code because the feature flag value is randomized each time +`Feature.enabled?` is called on your code path. + ##### Disabling feature flags To disable a feature flag that has been globally enabled you can run: @@ -250,7 +273,7 @@ Any feature flag change that affects GitLab.com (production) via [ChatOps](https is automatically logged in an issue. The issue is created in the -[gl-infra/feature-flag-log](https://gitlab.com/gitlab-com/gl-infra/feature-flag-log/-/issues?scope=all&utf8=%E2%9C%93&state=closed) +[gl-infra/feature-flag-log](https://gitlab.com/gitlab-com/gl-infra/feature-flag-log/-/issues?scope=all&state=closed) project, and it will at minimum log the Slack handle of person enabling a feature flag, the time, and the name of the flag being changed. diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md index 79efd6d5502..d7807c6f586 100644 --- a/doc/development/feature_flags/development.md +++ b/doc/development/feature_flags/development.md @@ -1,7 +1,9 @@ --- redirect_to: 'index.md' +remove_date: '2021-06-01' --- This document was moved to [another location](index.md). + <!-- This redirect file can be deleted after 2021-06-01. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index e18bcaa1f4e..79a100e44a5 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -41,7 +41,7 @@ should be leveraged: 1. [Create a new feature flag](#create-a-new-feature-flag) which is **off** by default, in the first merge request which uses the flag. - Flags [should not be added separately](#risk-of-a-broken-master-main-branch). + Flags [should not be added separately](#risk-of-a-broken-main-branch). 1. Submit incremental changes via one or more merge requests, ensuring that any new code added can only be reached if the feature flag is **on**. You can keep the feature flag enabled on your local GDK during development. @@ -59,11 +59,11 @@ flag does not have to stick around for a specific amount of time is deemed stable. Stable means it works on GitLab.com without causing any problems, such as outages. -## Risk of a broken master (main) branch +## Risk of a broken main branch -Feature flags **must** be used in the MR that introduces them. Not doing so causes a -[broken master](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) scenario due -to the `rspec:feature-flags` job that only runs on the `master` branch. +Feature flags must be used in the MR that introduces them. Not doing so causes a +[broken main branch](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) scenario due +to the `rspec:feature-flags` job that only runs on the `main` branch. ## Types of feature flags @@ -635,7 +635,7 @@ with how it interacts with `ActiveRecord`. ### End-to-end (QA) tests Toggling feature flags works differently in end-to-end (QA) tests. The end-to-end test framework does not have direct access to -Rails or the database, so it can't use Flipper. Instead, it uses [the public API](../../api/features.md#set-or-create-a-feature). Each end-to-end test can [enable or disable a feature flag during the test](../testing_guide/end_to_end/feature_flags.md). Alternatively, you can enable or disable a feature flag before one or more tests when you [run them from your GitLab repository's `qa` directory](https://gitlab.com/gitlab-org/gitlab/tree/master/qa#running-tests-with-a-feature-flag-enabled-or-disabled), or if you [run the tests via GitLab QA](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#running-tests-with-a-feature-flag-enabled). +Rails or the database, so it can't use Flipper. Instead, it uses [the public API](../../api/features.md#set-or-create-a-feature). Each end-to-end test can [enable or disable a feature flag during the test](../testing_guide/end_to_end/feature_flags.md). Alternatively, you can enable or disable a feature flag before one or more tests when you [run them from your GitLab repository's `qa` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa#running-tests-with-a-feature-flag-enabled-or-disabled), or if you [run the tests via GitLab QA](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#running-tests-with-a-feature-flag-enabled). [As noted above, feature flags are not enabled by default in end-to-end tests.](#feature-flags-in-tests) This means that end-to-end tests will run with feature flags in the default state implemented in the source diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md index 247dafe9f0b..0e962218ab9 100644 --- a/doc/development/feature_flags/process.md +++ b/doc/development/feature_flags/process.md @@ -1,5 +1,6 @@ --- redirect_to: 'https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/' +remove_date: '2021-06-01' --- This document was moved to [another location](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/). diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index 1f929d64058..71fc81a6ea3 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -60,7 +60,7 @@ hash of the project ID instead, if project migrates to the new approach (introdu We provide an [all-in-one Rake task](../administration/raketasks/uploads/migrate.md) to migrate all uploads to object storage in one go. If a new Uploader class or model type is introduced, make sure you add a Rake task invocation corresponding to it to the -[category list](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/uploads/migrate.rake). +[category list](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/gitlab/uploads/migrate.rake). ### Path segments diff --git a/doc/development/geo.md b/doc/development/geo.md index 05fadcad08a..8017bd21126 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -199,8 +199,8 @@ needs to be applied to the tracking database on each **secondary** node. ### Configuration -The database configuration is set in [`config/database_geo.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/config/database_geo.yml.postgresql). -The directory [`ee/db/geo`](https://gitlab.com/gitlab-org/gitlab/tree/master/ee/db/geo) +The database configuration is set in [`config/database_geo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/database_geo.yml.postgresql). +The directory [`ee/db/geo`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/db/geo) contains the schema and migrations for this database. To write a migration for the database, use the `GeoMigrationGenerator`: @@ -217,7 +217,7 @@ bundle exec rake geo:db:migrate ## Finders -Geo uses [Finders](https://gitlab.com/gitlab-org/gitlab/tree/master/app/finders), +Geo uses [Finders](https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/finders), which are classes take care of the heavy lifting of looking up projects/attachments/etc. in the tracking database and main database. @@ -320,7 +320,7 @@ The process running on the **secondary** node that looks for new ### `Gitlab::Geo` utilities Small utility methods related to Geo go into the -[`ee/lib/gitlab/geo.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/gitlab/geo.rb) +[`ee/lib/gitlab/geo.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/geo.rb) file. Many of these methods are cached using the `RequestStore` class, to diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 1513b65d19f..ad24353fde8 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -159,7 +159,7 @@ In some cases, such as building a Go project for it to act as a dependency of a CI run for another project, removing the `vendor/` directory means the code must be downloaded repeatedly, which can lead to intermittent problems due to rate limiting or network failures. In these circumstances, you should [cache the -downloaded code between](../../ci/caching/index.md#caching-go-dependencies). +downloaded code between](../../ci/caching/index.md#cache-go-dependencies). There was a [bug on modules checksums](https://github.com/golang/go/issues/29278) in Go versions earlier than v1.11.4, so make diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index a506b67d89d..40598eaff95 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -196,7 +196,7 @@ RuboCop](https://gitlab.com/gitlab-org/gitlab-foss/blob/8-4-stable/.rubocop.yml# Using the inline `:javascript` Haml filters comes with a performance overhead. Using inline JavaScript is not a good way to structure your code and should be avoided. -We've [removed these two filters](https://gitlab.com/gitlab-org/gitlab/blob/master/config/initializers/hamlit.rb) +We've [removed these two filters](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/hamlit.rb) in an initializer. ### Further reading diff --git a/doc/development/graphql_guide/authorization.md b/doc/development/graphql_guide/authorization.md index 8f17a8b6c93..a317b5d805b 100644 --- a/doc/development/graphql_guide/authorization.md +++ b/doc/development/graphql_guide/authorization.md @@ -40,7 +40,7 @@ to filter the records. This minimizes database queries and unnecessary authorization checks of the loaded records. It also avoids situations, such as short pages, which can expose the presence of confidential resources. -See [`authorization_spec.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/graphql/features/authorization_spec.rb) +See [`authorization_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/graphql/features/authorization_spec.rb) for examples of all the authorization schemes discussed here. ## Type authorization diff --git a/doc/development/graphql_guide/pagination.md b/doc/development/graphql_guide/pagination.md index 5db9238faed..5fd2179ea9b 100644 --- a/doc/development/graphql_guide/pagination.md +++ b/doc/development/graphql_guide/pagination.md @@ -223,6 +223,26 @@ the `order_due_date_and_labels_priority` method creates a very complex query. These types of queries are not supported. In these instances, you can use offset pagination. +#### Gotchas + +Do not define a collection's order using the string syntax: + +```ruby +# Bad +items.order('created_at DESC') +``` + +Instead, use the hash syntax: + +```ruby +# Good +items.order(created_at: :desc) +``` + +The first example won't correctly embed the sort information (`created_at`, in +the example above) into the pagination cursors, which will result in an +incorrect sort order. + ### Offset pagination There are times when the [complexity of sorting](#limitations-of-query-complexity) @@ -267,7 +287,7 @@ For consistency, we manually set the pagination cursors based on values returned You can see an example implementation in the following files: - [`types/error__tracking/sentry_error_collection_type.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/error_tracking/sentry_error_collection_type.rb) which adds an extension to `field :errors`. -- [`resolvers/error_tracking/sentry_errors_resolver.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/graphql/resolvers/error_tracking/sentry_errors_resolver.rb) which returns the data from the resolver. +- [`resolvers/error_tracking/sentry_errors_resolver.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/error_tracking/sentry_errors_resolver.rb) which returns the data from the resolver. ## Testing diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index b177a7e0138..7ea8378b6db 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -10,16 +10,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w For working with internationalization (i18n), [GNU gettext](https://www.gnu.org/software/gettext/) is used given it's the most -used tool for this task and there are a lot of applications that help us -work with it. +used tool for this task and there are many applications that help us work with it. NOTE: -All `rake` commands described on this page must be run on a GitLab instance, usually GDK. +All `rake` commands described on this page must be run on a GitLab instance. This instance is +usually the GitLab Development Kit (GDK). -## Setting up GitLab Development Kit (GDK) +## Setting up the GitLab Development Kit (GDK) -In order to be able to work on the [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss) -project you must download and configure it through [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/set-up-gdk.md). +To work on the [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss) +project, you must download and configure it through the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/set-up-gdk.md). After you have the GitLab project ready, you can start working on the translation. @@ -27,34 +27,33 @@ After you have the GitLab project ready, you can start working on the translatio The following tools are used: -1. [`gettext_i18n_rails`](https://github.com/grosser/gettext_i18n_rails): this - gem allow us to translate content from models, views and controllers. Also - it gives us access to the following Rake tasks: - - `rake gettext:find`: Parses almost all the files from the - Rails application looking for content that has been marked for - translation. Finally, it updates the PO files with the new content that - it has found. - - `rake gettext:pack`: Processes the PO files and generates the - MO files that are binary and are finally used by the application. - -1. [`gettext_i18n_rails_js`](https://github.com/webhippie/gettext_i18n_rails_js): - this gem is useful to make the translations available in JavaScript. It - provides the following Rake task: - - `rake gettext:po_to_json`: Reads the contents from the PO files and - generates JSON files containing all the available translations. - -1. PO editor: there are multiple applications that can help us to work with PO - files, a good option is [Poedit](https://poedit.net/download) which is - available for macOS, GNU/Linux and Windows. +- [`gettext_i18n_rails`](https://github.com/grosser/gettext_i18n_rails): + this gem allows us to translate content from models, views, and controllers. It also gives us + access to the following Rake tasks: + + - `rake gettext:find`: parses almost all the files from the Rails application looking for content + marked for translation. It then updates the PO files with this content. + - `rake gettext:pack`: processes the PO files and generates the binary MO files that the + application uses. + +- [`gettext_i18n_rails_js`](https://github.com/webhippie/gettext_i18n_rails_js): + this gem makes the translations available in JavaScript. It provides the following Rake task: + + - `rake gettext:po_to_json`: reads the contents of the PO files and generates JSON files that + contain all the available translations. + +- PO editor: there are multiple applications that can help us work with PO files. A good option is + [Poedit](https://poedit.net/download), + which is available for macOS, GNU/Linux, and Windows. ## Preparing a page for translation -We basically have 4 types of files: +There are four file types: -1. Ruby files: basically Models and Controllers. -1. HAML files: these are the view files. -1. ERB files: used for email templates. -1. JavaScript files: we mostly need to work with Vue templates. +- Ruby files: models and controllers. +- HAML files: view files. +- ERB files: used for email templates. +- JavaScript files: we mostly work with Vue templates. ### Ruby files @@ -72,7 +71,7 @@ Or: hello = "Hello world!" ``` -You can easily mark that content for translation with: +You can mark that content for translation with: ```ruby def hello @@ -86,26 +85,21 @@ Or: hello = _("Hello world!") ``` -Be careful when translating strings at the class or module level since these would only be -evaluated once at class load time. - -For example: +Be careful when translating strings at the class or module level since these are only evaluated once +at class load time. For example: ```ruby validates :group_id, uniqueness: { scope: [:project_id], message: _("already shared with this group") } ``` -This would be translated when the class is loaded and result in the error message -always being in the default locale. - -Active Record's `:message` option accepts a `Proc`, so we can do this instead: +This is translated when the class loads and results in the error message always being in the default +locale. Active Record's `:message` option accepts a `Proc`, so do this instead: ```ruby validates :group_id, uniqueness: { scope: [:project_id], message: -> (object, data) { _("already shared with this group") } } ``` -Messages in the API (`lib/api/` or `app/graphql`) do -not need to be externalized. +Messages in the API (`lib/api/` or `app/graphql`) do not need to be externalized. ### HAML files @@ -145,13 +139,20 @@ import { __ } from '~/locale'; const label = __('Subscribe'); ``` -In order to test JavaScript translations you have to change the GitLab -localization to another language than English and you have to generate JSON files -using `bin/rake gettext:po_to_json` or `bin/rake gettext:compile`. +To test JavaScript translations you must: + +- Change the GitLab localization to a language other than English. +- Generate JSON files by using `bin/rake gettext:po_to_json` or `bin/rake gettext:compile`. ### Vue files -In Vue files we make both the `__()` (double underscore parenthesis) function and the `s__()` (namespaced double underscore parenthesis) function available that you can import from the `~/locale` file. For instance: +In Vue files, we make the following functions available: + +- `__()` (double underscore parenthesis) +- `s__()` (namespaced double underscore parenthesis) + +You can therefore import from the `~/locale` file. +For example: ```javascript import { __, s__ } from '~/locale'; @@ -228,24 +229,24 @@ For the static text strings we suggest two patterns for using these translations </template> ``` -In order to visually test the Vue translations you have to change the GitLab -localization to another language than English and you have to generate JSON files -using `bin/rake gettext:po_to_json` or `bin/rake gettext:compile`. +To visually test the Vue translations: -### Dynamic translations +1. Change the GitLab localization to another language than English. +1. Generate JSON files using `bin/rake gettext:po_to_json` or `bin/rake gettext:compile`. -Sometimes there are some dynamic translations that can't be found by the -parser when running `bin/rake gettext:find`. For these scenarios you can -use the [`N_` method](https://github.com/grosser/gettext_i18n_rails/blob/c09e38d481e0899ca7d3fc01786834fa8e7aab97/Readme.md#unfound-translations-with-rake-gettextfind). +### Dynamic translations -There is also and alternative method to [translate messages from validation errors](https://github.com/grosser/gettext_i18n_rails/blob/c09e38d481e0899ca7d3fc01786834fa8e7aab97/Readme.md#option-a). +Sometimes there are dynamic translations that the parser can't find when running +`bin/rake gettext:find`. For these scenarios you can use the [`N_` method](https://github.com/grosser/gettext_i18n_rails/blob/c09e38d481e0899ca7d3fc01786834fa8e7aab97/Readme.md#unfound-translations-with-rake-gettextfind). +There's also an alternative method to [translate messages from validation errors](https://github.com/grosser/gettext_i18n_rails/blob/c09e38d481e0899ca7d3fc01786834fa8e7aab97/Readme.md#option-a). ## Working with special content ### Interpolation -Placeholders in translated text should match the code style of the respective source file. -For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make sure to [avoid splitting sentences when adding links](#avoid-splitting-sentences-when-adding-links). +Placeholders in translated text should match the respective source file's code style. For example +use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make sure to +[avoid splitting sentences when adding links](#avoid-splitting-sentences-when-adding-links). - In Ruby/HAML: @@ -257,9 +258,9 @@ For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make s Use the [`GlSprintf`](https://gitlab-org.gitlab.io/gitlab-ui/?path=/docs/utilities-sprintf--sentence-with-link) component if: - - you need to include child components in the translation string. - - you need to include HTML in your translation string. - - you are using `sprintf` and need to pass `false` as the third argument to + - You need to include child components in the translation string. + - You need to include HTML in your translation string. + - You're using `sprintf` and need to pass `false` as the third argument to prevent it from escaping placeholder values. For example: @@ -272,7 +273,7 @@ For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make s </gl-sprintf> ``` - In other cases it may be simpler to use `sprintf`, perhaps in a computed + In other cases, it might be simpler to use `sprintf`, perhaps in a computed property. For example: ```html @@ -344,7 +345,8 @@ For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make s # => When size == 2: 'There are 2 mice.' ``` - Avoid using `%d` or count variables in singular strings. This allows more natural translation in some languages. + Avoid using `%d` or count variables in singular strings. This allows more natural translation in + some languages. - In JavaScript: @@ -363,13 +365,12 @@ For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make s The `n_` method should only be used to fetch pluralized translations of the same string, not to control the logic of showing different strings for different -quantities. Some languages have different quantities of target plural forms - -Chinese (simplified), for example, has only one target plural form in our -translation tool. This means the translator would have to choose to translate -only one of the strings and the translation would not behave as intended in the -other case. +quantities. Some languages have different quantities of target plural forms. +For example, Chinese (simplified) has only one target plural form in our +translation tool. This means the translator has to choose to translate only one +of the strings, and the translation doesn't behave as intended in the other case. -For example, prefer to use: +For example, use this: ```ruby if selected_projects.one? @@ -379,7 +380,7 @@ else end ``` -rather than: +Instead of this: ```ruby # incorrect usage example @@ -388,21 +389,22 @@ n_("%{project_name}", "%d projects selected", count) % { project_name: 'GitLab' ### Namespaces -A namespace is a way to group translations that belong together. They provide context to our translators by adding a prefix followed by the bar symbol (`|`). For example: +A namespace is a way to group translations that belong together. They provide context to our +translators by adding a prefix followed by the bar symbol (`|`). For example: ```ruby 'Namespace|Translated string' ``` -A namespace provide the following benefits: +A namespace: -- It addresses ambiguity in words, for example: `Promotions|Promote` vs `Epic|Promote` -- It allows translators to focus on translating externalized strings that belong to the same product area rather than arbitrary ones. -- It gives a linguistic context to help the translator. +- Addresses ambiguity in words. For example: `Promotions|Promote` vs `Epic|Promote`. +- Allows translators to focus on translating externalized strings that belong to the same product + area, rather than arbitrary ones. +- Gives a linguistic context to help the translator. -In some cases, namespaces don't make sense, for example, -for ubiquitous UI words and phrases such as "Cancel" or phrases like "Save changes" a namespace could -be counterproductive. +In some cases, namespaces don't make sense. For example, for ubiquitous UI words and phrases such as +"Cancel" or phrases like "Save changes," a namespace could be counterproductive. Namespaces should be PascalCase. @@ -412,7 +414,7 @@ Namespaces should be PascalCase. s_('OpenedNDaysAgo|Opened') ``` - In case the translation is not found it returns `Opened`. + If the translation isn't found, `Opened` is returned. - In JavaScript: @@ -420,18 +422,19 @@ Namespaces should be PascalCase. s__('OpenedNDaysAgo|Opened') ``` -The namespace should be removed from the translation. See the -[translation guidelines for more details](translation.md#namespaced-strings). +The namespace should be removed from the translation. For more details, see the +[translation guidelines](translation.md#namespaced-strings). ### HTML -We no longer include HTML directly in the strings that are submitted for translation. This is for a couple of reasons: +We no longer include HTML directly in the strings that are submitted for translation. This is +because: -1. It introduces a chance for the translated string to accidentally include invalid HTML. -1. It introduces a security risk where translated strings become an attack vector for XSS, as noted by the +1. The translated string can accidentally include invalid HTML. +1. Translated strings can become an attack vector for XSS, as noted by the [Open Web Application Security Project (OWASP)](https://owasp.org/www-community/attacks/xss/). -To include formatting in the translated string, we can do the following: +To include formatting in the translated string, you can do the following: - In Ruby/HAML: @@ -449,18 +452,18 @@ To include formatting in the translated string, we can do the following: // => 'Some <strong>bold</strong> text.' ``` -- In Vue +- In Vue: See the section on [interpolation](#interpolation). -When [this translation helper issue](https://gitlab.com/gitlab-org/gitlab/-/issues/217935) is complete, we plan to update the -process of including formatting in translated strings. +When [this translation helper issue](https://gitlab.com/gitlab-org/gitlab/-/issues/217935) +is complete, we plan to update the process of including formatting in translated strings. #### Including Angle Brackets -If a string contains angles brackets (`<`/`>`) that are not used for HTML, it is still flagged by the -`rake gettext:lint` linter. -To avoid this error, use the applicable HTML entity code (`<` or `>`) instead: +If a string contains angle brackets (`<`/`>`) that are not used for HTML, the `rake gettext:lint` +linter still flags it. To avoid this error, use the applicable HTML entity code (`<` or `>`) +instead: - In Ruby/HAML: @@ -493,12 +496,12 @@ To avoid this error, use the applicable HTML entity code (`<` or `>`) inst ### Numbers -Different locales may use different number formats. To support localization of numbers, we use `formatNumber`, -which leverages [`toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString). +Different locales may use different number formats. To support localization of numbers, we use +`formatNumber`, which leverages [`toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString). -`formatNumber` formats numbers as strings using the current user locale by default. +By default, `formatNumber` formats numbers as strings using the current user locale. -- In JavaScript +- In JavaScript: ```javascript import { formatNumber } from '~/locale'; @@ -509,7 +512,7 @@ const tenThousand = formatNumber(10000); // "10,000" (uses comma as decimal symb const fiftyPercent = formatNumber(0.5, { style: 'percent' }) // "50%" (other options are passed to toLocaleString) ``` -- In Vue templates +- In Vue templates: ```html <script> @@ -546,27 +549,29 @@ console.log(dateFormat.format(new Date('2063-04-05'))) // April 5, 2063 This makes use of [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). -- In Ruby/HAML, we have two ways of adding format to dates and times: +- In Ruby/HAML, there are two ways of adding format to dates and times: - 1. **Through the `l` helper**, i.e. `l(active_session.created_at, format: :short)`. We have some predefined formats for - [dates](https://gitlab.com/gitlab-org/gitlab/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/config/locales/en.yml#L54) and [times](https://gitlab.com/gitlab-org/gitlab/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/config/locales/en.yml#L262). - If you need to add a new format, because other parts of the code could benefit from it, - you can add it to [en.yml](https://gitlab.com/gitlab-org/gitlab/blob/master/config/locales/en.yml) file. - 1. **Through `strftime`**, i.e. `milestone.start_date.strftime('%b %-d')`. We use `strftime` in case none of the formats - defined on [en.yml](https://gitlab.com/gitlab-org/gitlab/blob/master/config/locales/en.yml) matches the date/time - specifications we need, and if there is no need to add it as a new format because is very particular (i.e. it's only used in a single view). + - **Using the `l` helper**: for example, `l(active_session.created_at, format: :short)`. We have + some predefined formats for [dates](https://gitlab.com/gitlab-org/gitlab/-/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/config/locales/en.yml#L54) + and [times](https://gitlab.com/gitlab-org/gitlab/-/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/config/locales/en.yml#L262). + If you need to add a new format, because other parts of the code could benefit from it, add it + to the file [`en.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/locales/en.yml). + - **Using `strftime`**: for example, `milestone.start_date.strftime('%b %-d')`. We use `strftime` + in case none of the formats defined in [`en.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/locales/en.yml) + match the date/time specifications we need, and if there's no need to add it as a new format + because it's very particular (for example, it's only used in a single view). ## Best practices ### Minimize translation updates -Updates can result in the loss of the translations for this string. To minimize risks, -avoid changes to strings, unless they: +Updates can result in the loss of the translations for this string. To minimize risks, avoid changes +to strings unless they: -- Add value to the user. +- Add value for the user. - Include extra context for translators. -For example, we should avoid changes like this: +For example, avoid changes like this: ```diff - _('Number of things: %{count}') % { count: 10 } @@ -582,9 +587,10 @@ Examples: - Mappings for a dropdown list - Error messages -To store these kinds of data, using a constant seems like the best choice, however this doesn't work for translations. +To store these kinds of data, using a constant seems like the best choice. However, this doesn't +work for translations. -Bad, avoid it: +For example, avoid this: ```ruby class MyPresenter @@ -596,11 +602,13 @@ class MyPresenter end ``` -The translation method (`_`) is called when the class is loaded for the first time and translates the text to the default locale. Regardless of the user's locale, these values are not translated a second time. +The translation method (`_`) is called when the class loads for the first time and translates the +text to the default locale. Regardless of the user's locale, these values are not translated a +second time. -Similar thing happens when using class methods with memoization. +A similar thing happens when using class methods with memoization. -Bad, avoid it: +For example, avoid this: ```ruby class MyModel @@ -614,7 +622,7 @@ class MyModel end ``` -This method memorizes the translations using the locale of the user, who first "called" this method. +This method memoizes the translations using the locale of the user who first called this method. To avoid these problems, keep the translations dynamic. @@ -634,10 +642,10 @@ end ### Splitting sentences -Please never split a sentence as that would assume the sentence grammar and -structure is the same in all languages. +Never split a sentence, as it assumes the sentence's grammar and structure is the same in all +languages. -For instance, the following: +For example, this: ```javascript {{ s__("mrWidget|Set by") }} @@ -645,7 +653,7 @@ For instance, the following: {{ s__("mrWidget|to be merged automatically when the pipeline succeeds") }} ``` -should be externalized as follows: +Should be externalized as follows: ```javascript {{ sprintf(s__("mrWidget|Set by %{author} to be merged automatically when the pipeline succeeds"), { author: author.name }) }} @@ -653,7 +661,8 @@ should be externalized as follows: #### Avoid splitting sentences when adding links -This also applies when using links in between translated sentences, otherwise these texts are not translatable in certain languages. +This also applies when using links in between translated sentences. Otherwise, these texts are not +translatable in certain languages. - In Ruby/HAML, instead of: @@ -662,7 +671,7 @@ This also applies when using links in between translated sentences, otherwise th = s_('ClusterIntegration|Learn more about %{zones_link}').html_safe % { zones_link: zones_link } ``` - Set the link starting and ending HTML fragments as variables like so: + Set the link starting and ending HTML fragments as variables: ```haml - zones_link_url = 'https://cloud.google.com/compute/docs/regions-zones/regions-zones' @@ -687,7 +696,7 @@ This also applies when using links in between translated sentences, otherwise th </template> ``` - Set the link starting and ending HTML fragments as placeholders like so: + Set the link starting and ending HTML fragments as placeholders: ```html <template> @@ -714,7 +723,7 @@ This also applies when using links in between translated sentences, otherwise th }} ``` - Set the link starting and ending HTML fragments as placeholders like so: + Set the link starting and ending HTML fragments as placeholders: ```javascript {{ @@ -725,50 +734,47 @@ This also applies when using links in between translated sentences, otherwise th }} ``` -The reasoning behind this is that in some languages words change depending on context. For example in Japanese は is added to the subject of a sentence and を to the object. This is impossible to translate correctly if we extract individual words from the sentence. +The reasoning behind this is that in some languages words change depending on context. For example, +in Japanese は is added to the subject of a sentence and を to the object. This is impossible to +translate correctly if you extract individual words from the sentence. -When in doubt, try to follow the best practices described in this [Mozilla -Developer documentation](https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_content_best_practices#Splitting). +When in doubt, try to follow the best practices described in this [Mozilla Developer documentation](https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_content_best_practices#Splitting). ## Updating the PO files with the new content -Now that the new content is marked for translation, we need to update -`locale/gitlab.pot` files with the following command: +Now that the new content is marked for translation, run this command to update the +`locale/gitlab.pot` files: ```shell bin/rake gettext:regenerate ``` -This command updates `locale/gitlab.pot` file with the newly externalized -strings and remove any strings that aren't used anymore. You should check this -file in. Once the changes are on the default branch, they are picked up by -[CrowdIn](https://translate.gitlab.com) and be presented for -translation. +This command updates the `locale/gitlab.pot` file with the newly externalized strings and removes +any unused strings. Once the changes are on the default branch, [CrowdIn](https://translate.gitlab.com) +picks them up and presents them for translation. -We don't need to check in any changes to the `locale/[language]/gitlab.po` files. -They are updated automatically when [translations from CrowdIn are merged](merging_translations.md). +You don't need to check in any changes to the `locale/[language]/gitlab.po` files. They are updated +automatically when [translations from CrowdIn are merged](merging_translations.md). -If there are merge conflicts in the `gitlab.pot` file, you can delete the file -and regenerate it using the same command. +If there are merge conflicts in the `gitlab.pot` file, you can delete the file and regenerate it +using the same command. ### Validating PO files -To make sure we keep our translation files up to date, there's a linter that is -running on CI as part of the `static-analysis` job. - -To lint the adjustments in PO files locally you can run `rake gettext:lint`. +To make sure we keep our translation files up to date, there's a linter that runs on CI as part of +the `static-analysis` job. To lint the adjustments in PO files locally, you can run +`rake gettext:lint`. The linter takes the following into account: -- Valid PO-file syntax -- Variable usage - - Only one unnamed (`%d`) variable, since the order of variables might change - in different languages - - All variables used in the message ID are used in the translation - - There should be no variables used in a translation that aren't in the - message ID +- Valid PO-file syntax. +- Variable usage. + - Only one unnamed (`%d`) variable, since the order of variables might change in different + languages. + - All variables used in the message ID are used in the translation. + - There should be no variables used in a translation that aren't in the message ID. - Errors during translation. -- Presence of angle brackets (`<` or `>`) +- Presence of angle brackets (`<` or `>`). The errors are grouped per file, and per message ID: @@ -789,9 +795,8 @@ Errors in `locale/zh_TW/gitlab.po`: Failure translating to zh_TW with []: too few arguments ``` -In this output the `locale/zh_HK/gitlab.po` has syntax errors. -The `locale/zh_TW/gitlab.po` has variables that are used in the translation that -aren't in the message with ID `1 pipeline`. +In this output, `locale/zh_HK/gitlab.po` has syntax errors. The file `locale/zh_TW/gitlab.po` has +variables in the translation that aren't in the message with ID `1 pipeline`. ## Adding a new language @@ -803,9 +808,9 @@ NOTE: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221012) in GitLab 13.3: Languages with less than 2% of translations are not available in the UI. -Let's suppose you want to add translations for a new language, let's say French. +Suppose you want to add translations for a new language, for example, French: -1. The first step is to register the new language in `lib/gitlab/i18n.rb`: +1. Register the new language in `lib/gitlab/i18n.rb`: ```ruby ... @@ -816,38 +821,33 @@ Let's suppose you want to add translations for a new language, let's say French. ... ``` -1. Next, you need to add the language: +1. Add the language: ```shell bin/rake gettext:add_language[fr] ``` - If you want to add a new language for a specific region, the command is similar, - you just need to separate the region with an underscore (`_`). For example: + If you want to add a new language for a specific region, the command is similar. You must + separate the region with an underscore (`_`), specify the region in capital letters. For example: ```shell bin/rake gettext:add_language[en_GB] ``` - Please note that you need to specify the region part in capitals. - -1. Now that the language is added, a new directory has been created under the - path: `locale/fr/`. You can now start using your PO editor to edit the PO file - located in: `locale/fr/gitlab.edit.po`. +1. Adding the language also creates a new directory at the path `locale/fr/`. You can now start + using your PO editor to edit the PO file located at `locale/fr/gitlab.edit.po`. -1. After you're done updating the translations, you need to process the PO files - in order to generate the binary MO files and finally update the JSON files - containing the translations: +1. After updating the translations, you must process the PO files to generate the binary MO files, + and update the JSON files containing the translations: ```shell bin/rake gettext:compile ``` -1. In order to see the translated content we need to change our preferred language - which can be found under the user's **Settings** (`/profile`). +1. To see the translated content, you must change your preferred language. You can find this under + the user's **Settings** (`/profile`). -1. After checking that the changes are ok, you can proceed to commit the new files. - For example: +1. After checking that the changes are ok, commit the new files. For example: ```shell git add locale/fr/ app/assets/javascripts/locale/fr/ diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md index b0e34052d2a..c22bb6ff020 100644 --- a/doc/development/i18n/index.md +++ b/doc/development/i18n/index.md @@ -6,52 +6,49 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Translate GitLab to your language -The text in the GitLab user interface is in American English by default. -Each string can be translated to other languages. -As each string is translated, it is added to the languages translation file, -and is made available in future releases of GitLab. +The text in the GitLab user interface is in American English by default. Each string can be +translated to other languages. As each string is translated, it's added to the languages translation +file and made available in future GitLab releases. -Contributions to translations are always needed. -Many strings are not yet available for translation because they have not been externalized. -Helping externalize strings benefits all languages. -Some translations are incomplete or inconsistent. -Translating strings helps complete and improve each language. - -## How to contribute +Contributions to translations are always needed. Many strings are not yet available for translation +because they have not been externalized. Helping externalize strings benefits all languages. Some +translations are incomplete or inconsistent. Translating strings helps complete and improve each +language. There are many ways you can contribute in translating GitLab. -### Externalize strings +## Externalize strings -Before a string can be translated, it must be externalized. -This is the process where English strings in the GitLab source code are wrapped in a function that -retrieves the translated string for the user's language. +Before a string can be translated, it must be externalized. This is the process where English +strings in the GitLab source code are wrapped in a function that retrieves the translated string for +the user's language. -As new features are added and existing features are updated, the surrounding strings are being -externalized, however, there are many parts of GitLab that still need more work to externalize all +As new features are added and existing features are updated, the surrounding strings are +externalized. However, there are many parts of GitLab that still need more work to externalize all strings. See [Externalization for GitLab](externalization.md). -### Translate strings +## Translate strings -The translation process is managed at <https://translate.gitlab.com> +The translation process is managed at [https://translate.gitlab.com](https://translate.gitlab.com) using [CrowdIn](https://crowdin.com/). -You need to create an account before you can submit translations. -Once you are signed in, select the language you wish to contribute translations to. +You must create a CrowdIn account before you can submit translations. Once you are signed in, select +the language you wish to contribute translations to. -Voting for translations is also valuable, helping to confirm good and flag inaccurate translations. +Voting for translations is also valuable, helping to confirm good translations and flag inaccurate +ones. See [Translation guidelines](translation.md). -### Proofreading +## Proofreading -Proofreading helps ensure the accuracy and consistency of translations. All -translations are proofread before being accepted. If a translations requires -changes, you are notified with a comment explaining why. +Proofreading helps ensure the accuracy and consistency of translations. All translations are +proofread before being accepted. If a translation requires changes, a comment explaining why +notifies you. -See [Proofreading Translations](proofreader.md) for more information on who's -able to proofread and instructions on becoming a proofreader yourself. +See [Proofreading Translations](proofreader.md) for more information on who can proofread and +instructions on becoming a proofreader yourself. ## Release diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md index 48474a68d16..e3211f5a8fc 100644 --- a/doc/development/i18n/merging_translations.md +++ b/doc/development/i18n/merging_translations.md @@ -9,43 +9,42 @@ info: To determine the technical writer assigned to the Stage/Group associated w CrowdIn automatically syncs the `gitlab.pot` file with the CrowdIn service, presenting newly added externalized strings to the community of translators. -[GitLab CrowdIn Bot](https://gitlab.com/gitlab-crowdin-bot) also creates merge requests +The [GitLab CrowdIn Bot](https://gitlab.com/gitlab-crowdin-bot) also creates merge requests to take newly approved translation submissions and merge them into the `locale/<language>/gitlab.po` -files. Check the [merge requests created by `gitlab-crowdin-bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot) +files. Check the [merge requests created by `gitlab-crowdin-bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&state=opened&author_username=gitlab-crowdin-bot) to see new and merged merge requests. ## Validation By default CrowdIn commits translations with `[skip ci]` in the commit -message. This is done to avoid a bunch of pipelines being run. Before -merging translations, make sure to trigger a pipeline to validate -translations, we have static analysis validating things CrowdIn -doesn't do. Create a new pipeline at `https://gitlab.com/gitlab-org/gitlab/pipelines/new` -(need Developer access permissions) for the `master-i18n` branch. +message. This avoids an excessive number of pipelines from running. +Before merging translations, make sure to trigger a pipeline to validate +translations. Static analysis validates things CrowdIn doesn't do. Create +a new pipeline at [`https://gitlab.com/gitlab-org/gitlab/pipelines/new`](https://gitlab.com/gitlab-org/gitlab/pipelines/new) +(need developer permissions) for the `master-i18n` branch. If there are validation errors, the easiest solution is to disapprove the offending string in CrowdIn, leaving a comment with what is -required to fix the offense. There is an +required to fix the errors. There's an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/23256) -suggesting to automate this process. Disapproving excludes the -invalid translation, the merge request is then updated within a few +that suggests automating this process. Disapproving excludes the +invalid translation. The merge request is then updated within a few minutes. -If the translation has failed validation due to angle brackets `<` or `>` -it should be disapproved on CrowdIn as our strings should be -using [variables](externalization.md#html) for HTML instead. +If the translation fails validation due to angle brackets (`<` or `>`), +it should be disapproved in CrowdIn. Our strings must use [variables](externalization.md#html) +for HTML instead. -It might be handy to pause the integration on the CrowdIn side for a -little while so translations don't keep coming. This can be done by -clicking `Pause sync` on the [CrowdIn integration settings -page](https://translate.gitlab.com/project/gitlab-ee/settings#integration). +It might be useful to pause the integration on the CrowdIn side for a +moment so translations don't keep coming. You can do this by clicking +**Pause sync** on the [CrowdIn integration settings page](https://translate.gitlab.com/project/gitlab-ee/settings#integration). ## Merging translations After all translations are determined to be appropriate and the pipelines pass, you can merge the translations into the default branch. When merging translations, -be sure to select the **Remove source branch** check box, which causes CrowdIn -to recreate the `master-i18n` from the default branch after merging the new +be sure to select the **Remove source branch** checkbox. This causes CrowdIn +to recreate the `master-i18n` branch from the default branch after merging the new translation. We are discussing [automating this entire process](https://gitlab.com/gitlab-org/gitlab/-/issues/19896). @@ -54,10 +53,8 @@ We are discussing [automating this entire process](https://gitlab.com/gitlab-org CrowdIn creates a new merge request as soon as the old one is closed or merged. But it does not recreate the `master-i18n` branch every -time. To force CrowdIn to recreate the branch, close any [open merge -request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot) -and delete the -[`master-18n`](https://gitlab.com/gitlab-org/gitlab/-/branches/all?utf8=✓&search=master-i18n). +time. To force CrowdIn to recreate the branch, close any [open merge requests](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&state=opened&author_username=gitlab-crowdin-bot) +and delete the [`master-18n`](https://gitlab.com/gitlab-org/gitlab/-/branches/all?utf8=✓&search=master-i18n) branch. This might be needed when the merge request contains failures that have been fixed on the default branch. @@ -76,8 +73,8 @@ recreate it with the following steps: 1. Sign in to CrowdIn with the GitLab integration. 1. Go to **Settings > Integrations > GitLab > Set Up Integration**. 1. Select the `gitlab-org/gitlab` repository. -1. In `Select Branches for Translation`, select `master`. -1. Ensure the `Service Branch Name` is `master-i18n`. +1. In **Select Branches for Translation**, select `master`. +1. Ensure the **Service Branch Name** is `master-i18n`. ## Manually update the translation levels @@ -85,3 +82,9 @@ There's no automated way to pull the translation levels from CrowdIn, to display this information in the language selection dropdown. Therefore, the translation levels are hard-coded in the `TRANSLATION_LEVELS` constant in [`i18n.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/i18n.rb), and must be regularly updated. + +To update the translation levels: + +1. Get the translation levels (percentage of approved words) from [Crowdin](https://crowdin.com/project/gitlab-ee/settings#translations). + +1. Update the hard-coded translation levels in [`i18n.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/i18n.rb#L40). diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index a15eb4c3bc2..fc19ab93ecd 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -87,6 +87,7 @@ are very appreciative of the work done by translators and proofreaders! - Polish - Filip Mech - [GitLab](https://gitlab.com/mehenz), [CrowdIn](https://crowdin.com/profile/mehenz) - Maksymilian Roman - [GitLab](https://gitlab.com/villaincandle), [CrowdIn](https://crowdin.com/profile/villaincandle) + - Jakub Gładykowski - [GitLab](https://gitlab.com/gladykov), [CrowdIn](https://crowdin.com/profile/gladykov) - Portuguese - Diogo Trindade - [GitLab](https://gitlab.com/luisdiogo2071317), [CrowdIn](https://crowdin.com/profile/ldiogotrindade) - Portuguese, Brazilian @@ -108,7 +109,7 @@ are very appreciative of the work done by translators and proofreaders! - Spanish - Pedro Garcia - [GitLab](https://gitlab.com/pedgarrod), [CrowdIn](https://crowdin.com/profile/breaking_pitt) - Swedish - - Proofreaders needed. + - Johannes Nilsson - [GitLab](https://gitlab.com/nlssn), [CrowdIn](https://crowdin.com/profile/nlssn) - Turkish - Ali Demirtaş - [GitLab](https://gitlab.com/alidemirtas), [CrowdIn](https://crowdin.com/profile/alidemirtas) - Rıfat Ünalmış (Rifat Unalmis) - [GitLab](https://gitlab.com/runalmis), [CrowdIn](https://crowdin.com/profile/runalmis) @@ -121,35 +122,35 @@ are very appreciative of the work done by translators and proofreaders! ## Become a proofreader -Before requesting Proofreader permissions in CrowdIn, be sure you have a history -of contributing translations to the GitLab project. +Before requesting proofreader permissions in CrowdIn, be sure you have a history of contributing +translations to the GitLab project. 1. Contribute translations to GitLab. See instructions for [translating GitLab](translation.md). - Translating GitLab is a community effort that requires team work and - attention to detail. Proofreaders play an important role helping new - contributors, and ensuring the consistency and quality of translations. - Your conduct and contributions as a translator should reflect this before - requesting to be a proofreader. + Translating GitLab is a community effort that requires teamwork and attention to detail. + Proofreaders play an important role helping new contributors, and ensuring the consistency and + quality of translations. Your conduct and contributions as a translator should reflect this + before requesting to be a proofreader. + +1. Request proofreader permissions by opening a merge request to add yourself to the list of + proofreaders. + + Open the [`proofreader.md` source file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/i18n/proofreader.md) and click **Edit**. -1. Request proofreader permissions by opening a merge request to add yourself - to the list of proofreaders. + Add your language in alphabetical order and add yourself to the list, including: - Open the [proofreader.md source file](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/development/i18n/proofreader.md) and click **Edit**. + - Name + - Link to your GitLab profile + - Link to your CrowdIn profile - Add your language in alphabetical order, and add yourself to the list - including: - - name - - link to your GitLab profile - - link to your CrowdIn profile + In the merge request description, include links to any projects you have previously translated. - In the merge request description, include links to any projects you have - previously translated. +1. [GitLab team members](https://about.gitlab.com/company/team/), + [Core team members](https://about.gitlab.com/community/core-team/), + or current proofreaders fluent in the language consider your request to become a proofreader + based on the merits of your previous translations. -1. Your request to become a proofreader is considered on the merits of - your previous translations by [GitLab team members](https://about.gitlab.com/company/team/) - or [Core team members](https://about.gitlab.com/community/core-team/) who are fluent in - the language or current proofreaders. - - When a request is made for the first proofreader for a language and there are no [GitLab team members](https://about.gitlab.com/company/team/) - or [Core team members](https://about.gitlab.com/community/core-team/) who speak the language, we shall request links to previous translation work in other communities or projects. + - If you request to become the first proofreader for a language and there are no GitLab or Core + team members who speak that language, we request links to previous translation work in other + communities or projects. diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md index f3d02e180e7..f2592d9a8b9 100644 --- a/doc/development/i18n/translation.md +++ b/doc/development/i18n/translation.md @@ -6,47 +6,39 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Translating GitLab -For managing the translation process we use [CrowdIn](https://crowdin.com). +For managing the translation process, we use [CrowdIn](https://crowdin.com). +To contribute translations at [`translate.gitlab.com`](https://translate.gitlab.com), +you must create a CrowdIn account. You may create a new account or use any of their supported +sign-in services. -## Using CrowdIn +## Language selections -The first step is to get familiar with CrowdIn. +GitLab is being translated into many languages. To select a language to contribute to: -### Sign In +1. Find the language that you want to contribute to, in the + [GitLab CrowdIn project](https://crowdin.com/project/gitlab-ee). -To contribute translations at <https://translate.gitlab.com> -you must create a CrowdIn account. -You may create a new account or use any of their supported sign in services. + - If the language you want is available, proceed to the next step. + - If the language you want is not available, + [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=✓&state=all&label_name[]=Category%3AInternationalization). + Notify our CrowdIn administrators by including `@gitlab-org/manage/import` in your issue. + - After the issue and any merge requests are complete, restart this procedure. -### Language Selections +1. View the list of files and folders. Select `gitlab.pot` to open the translation editor. -GitLab is being translated into many languages. - -1. Find the language that you want to contribute to, in our - [GitLab Crowdin project](https://crowdin.com/project/gitlab-ee). - - If the language that you're looking for is available, proceed - to the next step. - - If the language you are looking for is not available, - [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=✓&state=all&label_name[]=Category%3AInternationalization). Notify our Crowdin - administrators by including `@gitlab-org/manage/import` in your issue. - - After the issue/Merge Request is complete, restart this procedure. -1. Next, you can view list of files and folders. - Select `gitlab.pot` to open the translation editor. - -### Translation Editor +### Translation editor The online translation editor is the easiest way to contribute translations.  -1. Strings for translation are listed in the left panel -1. Translations are entered into the central panel. - Multiple translations are required for strings that contains plurals. - The string to be translated is shown above with glossary terms highlighted. - If the string to be translated is not clear, you can 'Request Context' +- Strings for translation are listed in the left panel. +- Translations are entered into the central panel. Multiple translations are required for strings + that contain plurals. The string to translate is shown in the above image with glossary terms + highlighted. If the string to translate isn't clear, you can request context. -A glossary of common terms is available in the right panel by clicking Terms. -Comments can be added to discuss a translation with the community. +A glossary of common terms is available in the **Terms** tab in the right panel. In the **Comments** +tab, you can add comments to discuss a translation with the community. Remember to **Save** each translation. @@ -56,21 +48,18 @@ Be sure to check the following guidelines before you translate any strings. ### Namespaced strings -When an externalized string is prepended with a namespace, e.g. -`s_('OpenedNDaysAgo|Opened')`, the namespace should be removed from the final -translation. -For example in French `OpenedNDaysAgo|Opened` would be translated to -`Ouvert•e`, not `OpenedNDaysAgo|Ouvert•e`. +When an externalized string is prepended with a namespace (for example, +`s_('OpenedNDaysAgo|Opened')`), the namespace should be removed from the final translation. For +example, in French, `OpenedNDaysAgo|Opened` is translated to `Ouvert•e`, not +`OpenedNDaysAgo|Ouvert•e`. ### Technical terms -Some technical terms should be treated like proper nouns and not be translated. - -Technical terms that should always be in English are noted in the glossary when -using <https://translate.gitlab.com>. - -This helps maintain a logical connection and consistency between tools (e.g. -`git` client) and GitLab. +You should treat some technical terms like proper nouns and not translate them. Technical terms that +should always be in English are noted in the glossary when using +[`translate.gitlab.com`](https://translate.gitlab.com). +This helps maintain a logical connection and consistency between tools (for example, a Git client) +and GitLab. ### Formality @@ -78,36 +67,33 @@ The level of formality used in software varies by language: | Language | Formality | Example | | -------- | --------- | ------- | -| French | formal | `vous` for `you` | -| German | informal | `du` for `you` | +| French | formal | `vous` for `you` | +| German | informal | `du` for `you` | -You can refer to other translated strings and notes in the glossary to assist -determining a suitable level of formality. +Refer to other translated strings and notes in the glossary to assist you in determining a suitable +level of formality. ### Inclusive language -[Diversity](https://about.gitlab.com/handbook/values/#diversity) is a GitLab value. -We ask you to avoid translations which exclude people based on their gender or -ethnicity. -In languages which distinguish between a male and female form, use both or -choose a neutral formulation. +[Diversity, inclusion, and belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion) +are GitLab values. We ask you to avoid translations that exclude people based on their gender or +ethnicity. In languages that distinguish between a male and female form, use both or choose a +neutral formulation. <!-- vale gitlab.Spelling = NO --> -For example in German, the word "user" can be translated into "Benutzer" (male) or "Benutzerin" (female). -Therefore "create a new user" would translate into "Benutzer(in) anlegen". +For example, in German, the word _user_ can be translated into _Benutzer_ (male) or _Benutzerin_ +(female). Therefore, _create a new user_ translates to _Benutzer(in) anlegen_. <!-- vale gitlab.Spelling = YES --> ### Updating the glossary -To propose additions to the glossary please +To propose additions to the glossary, please [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=✓&state=all&label_name[]=Category%3AInternationalization). -## French Translation Guidelines - -### Inclusive language in French +## French translation guidelines <!-- vale gitlab.Spelling = NO --> -In French, the "écriture inclusive" is now over (see on [Legifrance](https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000036068906/)). -So, to include both genders, write "Utilisateurs et utilisatrices" instead of "Utilisateur·rice·s". -When space is missing, the male gender should be used alone. +In French, the _écriture inclusive_ is now over (see on [Legifrance](https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000036068906/)). +To include both genders, write _Utilisateurs et utilisatrices_ instead of _Utilisateur·rice·s_. If +there is not enough space, use the male gender alone. <!-- vale gitlab.Spelling = YES --> diff --git a/doc/development/import_project.md b/doc/development/import_project.md index 0c8406e2ebc..71d8f8b34b9 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.md @@ -53,7 +53,7 @@ This method takes longer to import than the other methods and depends on several ### Importing via a Rake task -> The [Rake task](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/import_export/import.rake) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20724) in GitLab 12.6, replacing a GitLab.com Ruby script. +> The [Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/gitlab/import_export/import.rake) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20724) in GitLab 12.6, replacing a GitLab.com Ruby script. This script was introduced in GitLab 12.6 for importing large GitLab project exports. diff --git a/doc/development/integrations/codesandbox.md b/doc/development/integrations/codesandbox.md index 234f8c7fe0b..caef1cd045b 100644 --- a/doc/development/integrations/codesandbox.md +++ b/doc/development/integrations/codesandbox.md @@ -126,7 +126,7 @@ index 6eed627b502..1824669e881 100644 +++ b/app/models/application_setting_implementation.rb @@ -391,7 +391,7 @@ def static_objects_external_storage_enabled? # This will eventually be configurable - # https://gitlab.com/gitlab-org/gitlab/issues/208161 + # https://gitlab.com/gitlab-org/gitlab/-/issues/208161 def web_ide_clientside_preview_bundler_url - 'https://sandbox-prod.gitlab-static.net' + 'https://sandpack.local:8044' diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index f54abfd17fd..0e42055cba2 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -24,7 +24,8 @@ brew services start jenkins GitLab does not allow requests to localhost or the local network by default. When running Jenkins on your local machine, you need to enable local access. 1. Log into your GitLab instance as an administrator. -1. Go to **Admin Area > Settings > Network**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests** and check the following checkboxes: - **Allow requests to the local network from web hooks and services** diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index fe3135b72b6..c4d8dfd3b95 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -550,7 +550,7 @@ of the available SAST Analyzers and what data is currently available. The `remediations` field of the report is an array of remediation objects. Each remediation describes a patch that can be applied to -[automatically fix](../../user/application_security/vulnerabilities/index.md#remediate-a-vulnerability-automatically) +[resolve](../../user/application_security/vulnerabilities/index.md#resolve-a-vulnerability) a set of vulnerabilities. Here is an example of a report that contains remediations. diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md index fedd424309d..e6048bed152 100644 --- a/doc/development/integrations/secure_partner_integration.md +++ b/doc/development/integrations/secure_partner_integration.md @@ -90,7 +90,7 @@ and complete an integration with the Secure stage. - Documentation for [SAST reports](../../user/application_security/sast/index.md#reports-json-format). - Documentation for [Dependency Scanning reports](../../user/application_security/dependency_scanning/index.md#reports-json-format). - Documentation for [Container Scanning reports](../../user/application_security/container_scanning/index.md#reports-json-format). - - See this [example secure job definition that also defines the artifact created](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). + - See this [example secure job definition that also defines the artifact created](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). - If you need a new kind of scan or report, [create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new#) and add the label `devops::secure`. - Once the job is completed, the data can be seen: @@ -101,7 +101,7 @@ and complete an integration with the Secure stage. - Users can interact with the findings from your artifact within their workflow. They can dismiss the findings or accept them and create a backlog issue. - To automatically create issues without user interaction, use the [issue API](../../api/issues.md). 1. Optional: Provide auto-remediation steps: - - If you specified `remediations` in your artifact, it is proposed through our [automatic remediation](../../user/application_security/vulnerabilities/index.md#remediate-a-vulnerability-automatically) + - If you specified `remediations` in your artifact, it is proposed through our [remediation](../../user/application_security/vulnerabilities/index.md#resolve-a-vulnerability) interface. 1. Demo the integration to GitLab: - After you have tested and are ready to demo your integration please diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index 57dd1c0a65b..95139f731e1 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -76,7 +76,9 @@ POST /internal/allowed Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" "http://localhost:3001/api/v4/internal/allowed" +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \ + --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \ + "http://localhost:3001/api/v4/internal/allowed" ``` Example response: @@ -124,7 +126,8 @@ information for LFS clients when the repository is accessed over SSH. Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate" +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \ + --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate" ``` ```json @@ -258,7 +261,8 @@ GET /internal/two_factor_recovery_codes Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes" +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \ + --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes" ``` Example response: @@ -305,7 +309,9 @@ POST /internal/personal_access_token Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" "http://localhost:3001/api/v4/internal/personal_access_token" +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \ + --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \ + "http://localhost:3001/api/v4/internal/personal_access_token" ``` Example response: @@ -339,7 +345,8 @@ POST /internal/pre_receive Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive" +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \ + --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive" ``` Example response: @@ -371,7 +378,10 @@ POST /internal/post_receive Example Request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "gl_repository=project-7" --data "identifier=user-1" --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" "http://localhost:3001/api/v4/internal/post_receive" +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \ + --data "gl_repository=project-7" --data "identifier=user-1" \ + --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \ + "http://localhost:3001/api/v4/internal/post_receive" ``` Example response: @@ -418,7 +428,8 @@ GET /internal/kubernetes/agent_info Example Request: ```shell -curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info" +curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \ + --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info" ``` ### Kubernetes agent project information @@ -443,7 +454,8 @@ GET /internal/kubernetes/project_info Example Request: ```shell -curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7" +curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \ + --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7" ``` ### Kubernetes agent usage metrics @@ -463,7 +475,8 @@ POST /internal/kubernetes/usage_metrics Example Request: ```shell -curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Content-Type: application/json" --data '{"gitops_sync_count":1}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics" +curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Content-Type: application/json" \ + --data '{"gitops_sync_count":1}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics" ``` ### Kubernetes agent alert metrics @@ -482,7 +495,10 @@ POST internal/kubernetes/modules/cilium_alert Example Request: ```shell -curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" --data '"{\"alert\":{\"title\":\"minimal\",\"message\":\"network problem\",\"evalMatches\":[{\"value\":1,\"metric\":\"Count\",\"tags\":{}}]}}"' "http://localhost:3000/api/v4/internal/kubernetes/modules/cilium_alert" +curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \ + --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \ + --data '"{\"alert\":{\"title\":\"minimal\",\"message\":\"network problem\",\"evalMatches\":[{\"value\":1,\"metric\":\"Count\",\"tags\":{}}]}}"' \ + "http://localhost:3000/api/v4/internal/kubernetes/modules/cilium_alert" ``` ## Subscriptions diff --git a/doc/development/jh_features_review.md b/doc/development/jh_features_review.md index 260da2d7ef2..b139a380344 100644 --- a/doc/development/jh_features_review.md +++ b/doc/development/jh_features_review.md @@ -23,6 +23,12 @@ We have two kinds of changes related to JH: If needed, review the corresponding JH merge request located at [JH repository](https://gitlab.com/gitlab-jh/gitlab) +## Process overview + +See the [merge request process](https://about.gitlab.com/handbook/ceo/chief-of-staff-team/jihu-support/#merge-request-process) +on the JiHu Support handbook. +This page is the single source of truth for JiHu-related processes. + ## Act as EE when `jh/` does not exist - In the case of EE repository, `jh/` does not exist so it should just act like EE (or CE when the license is absent) diff --git a/doc/development/kubernetes.md b/doc/development/kubernetes.md index 5be2080eb64..9e67227ec7f 100644 --- a/doc/development/kubernetes.md +++ b/doc/development/kubernetes.md @@ -35,12 +35,12 @@ We use the [`kubeclient`](https://rubygems.org/gems/kubeclient) gem to perform Kubernetes API calls. As the `kubeclient` gem does not support different API Groups (such as `apis/rbac.authorization.k8s.io`) from a single client, we have created a wrapper class, -[`Gitlab::Kubernetes::KubeClient`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/kubernetes/kube_client.rb) +[`Gitlab::Kubernetes::KubeClient`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/kubernetes/kube_client.rb) that enable you to achieve this. Selected Kubernetes API groups are supported. Do add support for new API groups or methods to -[`Gitlab::Kubernetes::KubeClient`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/kubernetes/kube_client.rb) +[`Gitlab::Kubernetes::KubeClient`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/kubernetes/kube_client.rb) if you need to use them. New API groups or API group versions can be added to `SUPPORTED_API_GROUPS` - internally, this creates an internal client for that group. New methods can be added as a delegation @@ -50,7 +50,7 @@ to the relevant internal client. All calls to the Kubernetes API must be in a background process. Don't perform Kubernetes API calls within a web request. This blocks -Unicorn, and can lead to a denial-of-service (DoS) attack in GitLab as +webserver, and can lead to a denial-of-service (DoS) attack in GitLab as the Kubernetes cluster response times are outside of our control. The easiest way to ensure your calls happen a background process is to @@ -58,7 +58,7 @@ delegate any such work to happen in a [Sidekiq worker](sidekiq_style_guide.md). You may want to make calls to Kubernetes and return the response, but a background worker isn't a good fit. Consider using -[reactive caching](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/reactive_caching.rb). +[reactive caching](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/concerns/reactive_caching.rb). For example: ```ruby @@ -76,7 +76,7 @@ For example: ### Testing We have some WebMock stubs in -[`KubernetesHelpers`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/support/helpers/kubernetes_helpers.rb) +[`KubernetesHelpers`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/helpers/kubernetes_helpers.rb) which can help with mocking out calls to Kubernetes API in your tests. ### Amazon EKS integration @@ -107,7 +107,7 @@ The process for creating a cluster is as follows: by `:provision_role_arn` and stores a set of temporary credentials on the provider record. By default these credentials are valid for one hour. 1. A CloudFormation stack is created, based on the - [`AWS CloudFormation EKS template`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/aws/cloudformation/eks_cluster.yaml). + [`AWS CloudFormation EKS template`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/aws/cloudformation/eks_cluster.yaml). This triggers creation of all resources required for an EKS cluster. 1. GitLab polls the status of the stack until all resources are ready, which takes somewhere between 10 and 15 minutes in most cases. @@ -135,7 +135,7 @@ a cluster. Mitigation strategies include: 1. Not allowing redirects to attacker controller resources: - [`Kubeclient::KubeClient`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/kubernetes/kube_client.rb#) + [`Kubeclient::KubeClient`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/kubernetes/kube_client.rb#) can be configured to disallow any redirects by passing in `http_max_redirects: 0` as an option. 1. Not exposing error messages: by doing so, we @@ -159,7 +159,7 @@ Logs related to the Kubernetes integration can be found in GDK install, these logs are present in `log/kubernetes.log`. Some services such as -[`Clusters::Applications::InstallService`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/services/clusters/applications/install_service.rb#L18) +[`Clusters::Applications::InstallService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/clusters/applications/install_service.rb#L18) rescues `StandardError` which can make it harder to debug issues in an development environment. The current workaround is to temporarily comment out the `rescue` in your local development source. @@ -172,12 +172,3 @@ they are written: ```shell kubectl logs <pod_name> --follow -n gitlab-managed-apps ``` - -## GitLab Managed Apps - -GitLab provides [GitLab Managed Apps](../user/clusters/applications.md), a one-click -install for various applications which can be added directly to your configured cluster. - -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of how to add a new GitLab-managed app, see -[How to add GitLab-managed-apps to Kubernetes integration](https://youtu.be/mKm-jkranEk).** diff --git a/doc/development/licensing.md b/doc/development/licensing.md index 5f03013a780..23871bf3c68 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Licensing and Compatibility -[GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/) (CE) is licensed [under the terms of the MIT License](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/LICENSE). [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/) (EE) is licensed under "[The GitLab Enterprise Edition (EE) license](https://gitlab.com/gitlab-org/gitlab/blob/master/LICENSE)" wherein there are more restrictions. +[GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/) (CE) is licensed [under the terms of the MIT License](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/LICENSE). [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/) (EE) is licensed under "[The GitLab Enterprise Edition (EE) license](https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE)" wherein there are more restrictions. ## Automated Testing diff --git a/doc/development/logging.md b/doc/development/logging.md index 88ae3950f1a..45f5b672365 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -278,9 +278,9 @@ The API, Rails and Sidekiq logs contain fields starting with `meta.` with this c Entry points can be seen at: -- [`ApplicationController`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/application_controller.rb) -- [External API](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/api.rb) -- [Internal API](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/internal/base.rb) +- [`ApplicationController`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/application_controller.rb) +- [External API](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/api.rb) +- [Internal API](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/internal/base.rb) #### Adding attributes diff --git a/doc/development/maintenance_mode.md b/doc/development/maintenance_mode.md index f05a731a331..e308ab26c27 100644 --- a/doc/development/maintenance_mode.md +++ b/doc/development/maintenance_mode.md @@ -9,9 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Where is Maintenance Mode enforced? GitLab Maintenance Mode **only** blocks writes from HTTP and SSH requests at the application level in a few key places within the rails application. -[Search the codebase for `maintenance_mode?`.](https://gitlab.com/search?utf8=%E2%9C%93&search=maintenance_mode%3F&group_id=9970&project_id=278964&scope=blobs&search_code=false&snippets=false&repository_ref=) +[Search the codebase for `maintenance_mode?`.](https://gitlab.com/search?search=maintenance_mode%3F&group_id=9970&project_id=278964&scope=blobs&search_code=false&snippets=false&repository_ref=) -- [the read-only database method](https://gitlab.com/gitlab-org/gitlab/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/database.rb#L13), which toggles special behavior when we are not allowed to write to the database. [Search the codebase for `Gitlab::Database.read_only?`.](https://gitlab.com/search?utf8=%E2%9C%93&search=Gitlab%3A%3ADatabase.read_only%3F&group_id=9970&project_id=278964&scope=blobs&search_code=false&snippets=false&repository_ref=) +- [the read-only database method](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/database.rb#L13), which toggles special behavior when we are not allowed to write to the database. [Search the codebase for `Gitlab::Database.read_only?`.](https://gitlab.com/search?search=Gitlab%3A%3ADatabase.read_only%3F&group_id=9970&project_id=278964&scope=blobs&search_code=false&snippets=false&repository_ref=) - [the read-only middleware](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/ee/gitlab/middleware/read_only/controller.rb), where HTTP requests that cause database writes are blocked, unless explicitly allowed. - [Git push access via SSH is denied](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/git_access.rb#L13) by returning 401 when `gitlab-shell` POSTs to [`/internal/allowed`](internal_api.md) to [check if access is allowed](internal_api.md#git-authentication). - [Container registry authentication service](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/app/services/ee/auth/container_registry_authentication_service.rb#L12), where updates to the container registry are blocked. diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 543ca809f45..973d4042cda 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -292,13 +292,13 @@ in a batch style. **Summary:** You should set a reasonable timeout when the system invokes HTTP calls to external services (such as Kubernetes), and it should be executed in Sidekiq, not -in Puma/Unicorn threads. +in Puma threads. Often, GitLab needs to communicate with an external service such as Kubernetes clusters. In this case, it's hard to estimate when the external service finishes the requested process, for example, if it's a user-owned cluster that's inactive for some reason, GitLab might wait for the response forever ([Example](https://gitlab.com/gitlab-org/gitlab/-/issues/31475)). -This could result in Puma/Unicorn timeout and should be avoided at all cost. +This could result in Puma timeout and should be avoided at all cost. You should set a reasonable timeout, gracefully handle exceptions and surface the errors in UI or logging internally. @@ -598,10 +598,10 @@ Each feature that accepts data uploads or allows to download them needs to use saved directly to Object Storage by Workhorse, and all downloads needs to be served by Workhorse. -Performing uploads/downloads via Unicorn/Puma is an expensive operation, -as it blocks the whole processing slot (worker or thread) for the duration of the upload. +Performing uploads/downloads via Puma is an expensive operation, +as it blocks the whole processing slot (thread) for the duration of the upload. -Performing uploads/downloads via Unicorn/Puma also has a problem where the operation +Performing uploads/downloads via Puma also has a problem where the operation can time out, which is especially problematic for slow clients. If clients take a long time to upload/download the processing slot might be killed due to request processing timeout (usually between 30s-60s). diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index e1444f1a726..009ead8ba16 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -45,16 +45,16 @@ columns manually for existing tables as this causes confusion to other people using `db/structure.sql` generated by Rails. When your local database in your GDK is diverging from the schema from -`master` it might be hard to cleanly commit the schema changes to +`main` it might be hard to cleanly commit the schema changes to Git. In that case you can use the `scripts/regenerate-schema` script to regenerate a clean `db/structure.sql` for the migrations you're adding. This script applies all migrations found in `db/migrate` or `db/post_migrate`, so if there are any migrations you don't want to commit to the schema, rename or remove them. If your branch is not -targeting `master` you can set the `TARGET` environment variable. +targeting `main` you can set the `TARGET` environment variable. ```shell -# Regenerate schema against `master` +# Regenerate schema against `main` scripts/regenerate-schema # Regenerate schema against `12-9-stable-ee` @@ -844,7 +844,7 @@ You have to use a serializer to provide a translation layer: ```ruby class BuildMetadata - serialize :config_options, Serializers::JSON # rubocop:disable Cop/ActiveRecordSerialize + serialize :config_options, Serializers::Json # rubocop:disable Cop/ActiveRecordSerialize end ``` @@ -856,6 +856,37 @@ class BuildMetadata end ``` +## Encrypted attributes + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227779) in GitLab 14.0. + +Do not store `attr_encrypted` attributes as `:text` in the database; use +`:binary` instead. This uses the `bytea` type in PostgreSQL and makes storage more +efficient: + +```ruby +class AddSecretToSomething < ActiveRecord::Migration[5.0] + def change + add_column :something, :encrypted_secret, :binary + add_column :something, :encrypted_secret_iv, :binary + end +end +``` + +When storing encrypted attributes in a binary column, we need to provide the +`encode: false` and `encode_iv: false` options to `attr_encrypted`: + +```ruby +class Something < ApplicationRecord + attr_encrypted :secret, + mode: :per_attribute_iv, + key: Settings.attr_encrypted_db_key_base_32, + algorithm: 'aes-256-gcm', + encode: false, + encode_iv: false +end +``` + ## Testing See the [Testing Rails migrations](testing_guide/testing_migrations_guide.md) style guide. @@ -945,6 +976,9 @@ If using a model in the migrations, you should first [clear the column cache](https://api.rubyonrails.org/classes/ActiveRecord/ModelSchema/ClassMethods.html#method-i-reset_column_information) using `reset_column_information`. +If using a model that leverages single table inheritance (STI), there are [special +considerations](single_table_inheritance.md#in-migrations). + This avoids problems where a column that you are using was altered and cached in a previous migration. diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md index 16c7a807053..f298b603429 100644 --- a/doc/development/module_with_instance_variables.md +++ b/doc/development/module_with_instance_variables.md @@ -68,7 +68,7 @@ objects are touching them, then it would be an acceptable use. We especially allow the case where a single instance variable is used with `||=` to set up the value. This would look like: -``` ruby +```ruby module M def f @f ||= true @@ -85,7 +85,7 @@ we could easily add to the cop, we should do it. Even if we could just disable the cop, we should avoid doing so. Some code could be easily rewritten in simple form. Consider this acceptable method: -``` ruby +```ruby module Gitlab module Emoji def emoji_unicode_version(name) @@ -104,7 +104,7 @@ cop is not smart enough to judge that this is fine. On the other hand, we could split this method into two: -``` ruby +```ruby module Gitlab module Emoji def emoji_unicode_version(name) @@ -127,7 +127,7 @@ Now the cop doesn't complain. Put the disabling comment right after your code in the same line: -``` ruby +```ruby module M def violating_method @f + @g # rubocop:disable Gitlab/ModuleWithInstanceVariables @@ -137,7 +137,7 @@ end If there are multiple lines, you could also enable and disable for a section: -``` ruby +```ruby module M # rubocop:disable Gitlab/ModuleWithInstanceVariables def violating_method @@ -167,13 +167,13 @@ point of view), making it extremely hard to track data dependency. We're trying to use something like this instead: -``` haml +```haml = render 'projects/commits/commit', commit: commit, ref: ref, project: project ``` And in the partial: -``` haml +```haml - ref = local_assigns.fetch(:ref) - commit = local_assigns.fetch(:commit) - project = local_assigns.fetch(:project) diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md index 44e93bfb8a8..acdf8194cb1 100644 --- a/doc/development/multi_version_compatibility.md +++ b/doc/development/multi_version_compatibility.md @@ -4,47 +4,120 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Compatibility with multiple versions of the application running at the same time +# Backwards compatibility across updates -When adding or changing features, we must be aware that there may be multiple versions of the application running -at the same time and connected to the same PostgreSQL and Redis databases. This could happen during a rolling deploy -when the servers are updated one by one. +GitLab deployments can be broken down into many components. Updating GitLab is not atomic. Therefore, **many components must be backwards-compatible**. -During a rolling deploy, post-deployment DB migrations are run after all the servers have been updated. This means the -servers could be in these intermediate states: +## Common gotchas -1. Old application code running with new DB migrations already executed -1. New application code running with new DB migrations but without new post-deployment DB migrations +In a sense, these scenarios are all transient states. But they can often persist for several hours in a live, production environment. Therefore we must treat them with the same care as permanent states. -We must make sure that the application works properly in these states. +### When modifying a Sidekiq worker -For GitLab.com, we also run a set of canary servers which run a more recent version of the application. Users with -the canary cookie set would be handled by these servers. Some URL patterns may also be forced to the canary servers, -even without the cookie being set. This also means that some pages may match the pattern and get handled by canary servers, -but AJAX requests to URLs (like the GraphQL endpoint) fail to match the pattern. +For example when [changing arguments](sidekiq_style_guide.md#changing-the-arguments-for-a-worker): -With this canary setup, we'd be in this mixed-versions state for an extended period of time until canary is promoted to -production and post-deployment migrations run. +- Is it ok if jobs are being enqueued with the old signature but executed by the new monthly release? +- Is it ok if jobs are being enqueued with the new signature but executed by the previous monthly release? -Also be aware that during a deployment to production, Web, API, and -Sidekiq nodes are updated in parallel, but they may finish at -different times. That means there may be a window of time when the -application code is not in sync across the whole fleet. Changes that -cut across Sidekiq, Web, and/or the API may [introduce unexpected -errors until the deployment is complete](#builds-failing-due-to-varying-deployment-times-across-node-types). +### When adding a new Sidekiq worker + +Is it ok if these jobs don't get executed for several hours because [Sidekiq nodes are not yet updated](sidekiq_style_guide.md#adding-new-workers)? + +### When modifying JavaScript + +Is it ok when a browser has the new JavaScript code, but the Rails code is running the previous monthly release on: + +- the REST API? +- the GraphQL API? +- internal APIs in controllers? + +### When adding a pre-deployment migration + +Is it ok if the pre-deployment migration has executed, but the web, Sidekiq, and API nodes are running the previous release? + +### When adding a post-deployment migration + +Is it ok if all GitLab nodes have been updated, but the post-deployment migrations don't get executed until a couple days later? + +### When adding a background migration + +Is it ok if all nodes have been updated, and then the post-deployment migrations get executed a couple days later, and then the background migrations take a week to finish? + +## A walkthrough of an update + +Backwards compatibility problems during updates are often very subtle. This is why it is worth familiarizing yourself with [update instructions](../update/index.md), [reference architectures](../administration/reference_architectures/index.md), and [GitLab.com's architecture](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/). But to illustrate how these problems arise, take a look at this example of a simple update. + +- 🚢 New version +- 🙂 Old version + +In this example, you can imagine that we are updating by one monthly release. But refer to [How long must code be backwards-compatible?](#how-long-must-code-be-backwards-compatible). + +| Update step | Postgres DB | Web nodes | API nodes | Sidekiq nodes | Compatibility concerns | +| --- | --- | --- | --- | --- | --- | +| Initial state | 🙂 | 🙂 | 🙂 | 🙂 | | +| Ran pre-deployment migrations | 🚢 except post-deploy migrations | 🙂 | 🙂 | 🙂 | Rails code in 🙂 is making DB calls to 🚢 | +| Update web nodes | 🚢 except post-deploy migrations | 🚢 | 🙂 | 🙂 | JavaScript in 🚢 is making API calls to 🙂. Rails code in 🚢 is enqueuing jobs that are getting run by Sidekiq nodes in 🙂 | +| Update API and Sidekiq nodes | 🚢 except post-deploy migrations | 🚢 | 🚢 | 🚢 | Rails code in 🚢 is making DB calls without post-deployment migrations or background migrations | +| Run post-deployment migrations | 🚢 | 🚢 | 🚢 | 🚢 | Rails code in 🚢 is making DB calls without background migrations | +| Background migrations finish | 🚢 | 🚢 | 🚢 | 🚢 | | + +This example is not exhaustive. GitLab can be deployed in many different ways. Even each update step is not atomic. For example, with rolling deploys, nodes within a group are temporarily on different versions. You should assume that a lot of time passes between update steps. This is often true on GitLab.com. + +## How long must code be backwards-compatible? + +For users following [zero-downtime update instructions](../update/index.md#upgrading-without-downtime), the answer is one monthly release. For example: + +- 13.11 => 13.12 +- 13.12 => 14.0 +- 14.0 => 14.1 + +For GitLab.com, there can be multiple tiny version updates per day, so GitLab.com doesn't constrain how far changes must be backwards-compatible. + +Many users [skip some monthly releases](../update/index.md#upgrading-to-a-new-major-version), for example: + +- 13.0 => 13.12 + +These users accept some downtime during the update. Unfortunately we can't ignore this case completely. For example, 13.12 may execute Sidekiq jobs from 13.0, which illustrates why [we avoid removing arguments from jobs until a major release](sidekiq_style_guide.md#deprecate-and-remove-an-argument). The main question is: Will the deployment get to a good state after the update is complete? + +## What kind of components can GitLab be broken down into? + +The [50,000 reference architecture](../administration/reference_architectures/50k_users.md) runs GitLab on 48+ nodes. GitLab.com is [bigger than that](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/), plus a portion of the [infrastructure runs on Kubernetes](https://about.gitlab.com/handbook/engineering/infrastructure/production/kubernetes/gitlab-com/), plus there is a ["canary" stage which receives updates first](https://about.gitlab.com/handbook/engineering/#sts=Canary%20Testing). + +But the problem isn't just that there are many nodes. The bigger problem is that a deployment can be divided into different contexts. And GitLab.com is not the only one that does this. Some possible divisions: + +- "Canary web app nodes": Handle non-API requests from a subset of users +- "Git app nodes": Handle Git requests +- "Web app nodes": Handle web requests +- "API app nodes": Handle API requests +- "Sidekiq app nodes": Handle Sidekiq jobs +- "Postgres database": Handle internal Postgres calls +- "Redis database": Handle internal Redis calls +- "Gitaly nodes": Handle internal Gitaly calls + +During an update, there will be [two different versions of GitLab running in different contexts](#a-walkthrough-of-an-update). For example, [a web node may enqueue jobs which get run on an old Sidekiq node](#when-modifying-a-sidekiq-worker). + +## Doesn't the order of update steps matter? + +Yes! We have specific instructions for [zero-downtime updates](../update/index.md#upgrading-without-downtime) because it allows us to ignore some permutations of compatibility. This is why we don't worry about Rails code making DB calls to an old Postgres database schema. + +## I've identified a potential backwards compatibility problem, what can I do about it? + +### Feature flags One way to handle this is to use a feature flag that is disabled by default. The feature flag can be enabled when the deployment is in a -consistent state. However, this method of synchronization doesn't -guarantee that customers with on-premise instances can [upgrade with +consistent state. However, this method of synchronization **does not +guarantee** that customers with on-premise instances can [update with zero downtime](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates) -because point releases bundle many changes together. Minimizing the time -between when versions are out of sync across the fleet may help mitigate -errors caused by upgrades. +because point releases bundle many changes together. + +### Graceful degradation + +As an example, when adding a new feature with frontend and API changes, it may be possible to write the frontend such that the new feature degrades gracefully against old API responses. This may help avoid needing to spread a change over 3 releases. -## Requirements for zero downtime upgrades +### Expand and contract pattern -One way to guarantee zero downtime upgrades for on-premise instances is following the +One way to guarantee zero downtime updates for on-premise instances is following the [expand and contract pattern](https://martinfowler.com/bliki/ParallelChange.html). This means that every breaking change is broken down in three phases: expand, migrate, and contract. @@ -53,7 +126,7 @@ This means that every breaking change is broken down in three phases: expand, mi 1. **migrate**: all consumers are updated to make use of the new implementation. 1. **contract**: backward compatibility is removed. -Those three phases **must be part of different milestones**, to allow zero downtime upgrades. +Those three phases **must be part of different milestones**, to allow zero downtime updates. Depending on the support level for the feature, the contract phase could be delayed until the next major release. @@ -205,7 +278,7 @@ variable `CI_NODE_TOTAL` being an integer failed. This was caused because after 1. New code: Sidekiq created a new pipeline and new build. `build.options[:parallel]` is a `Hash`. 1. Old code: Runners requested a job from an API node that is running the previous version. -1. As a result, the [new code](https://gitlab.com/gitlab-org/gitlab/blob/42b82a9a3ac5a96f9152aad6cbc583c42b9fb082/app/models/concerns/ci/contextable.rb#L104) +1. As a result, the [new code](https://gitlab.com/gitlab-org/gitlab/-/blob/42b82a9a3ac5a96f9152aad6cbc583c42b9fb082/app/models/concerns/ci/contextable.rb#L104) was not run on the API server. The runner's request failed because the older API server tried return the `CI_NODE_TOTAL` CI/CD variable, but instead of sending an integer value (e.g. 9), it sent a serialized diff --git a/doc/development/namespaces_storage_statistics.md b/doc/development/namespaces_storage_statistics.md index 587e1091e77..232d421d883 100644 --- a/doc/development/namespaces_storage_statistics.md +++ b/doc/development/namespaces_storage_statistics.md @@ -20,11 +20,11 @@ storage consumed by a group, and allow easy management. ## Problem In GitLab, we update the project storage statistics through a -[callback](https://gitlab.com/gitlab-org/gitlab/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/app/models/project.rb#L97) +[callback](https://gitlab.com/gitlab-org/gitlab/-/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/app/models/project.rb#L97) every time the project is saved. The summary of those statistics per namespace is then retrieved -by [`Namespaces#with_statistics`](https://gitlab.com/gitlab-org/gitlab/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/app/models/namespace.rb#L70) scope. Analyzing this query we noticed that: +by [`Namespaces#with_statistics`](https://gitlab.com/gitlab-org/gitlab/-/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/app/models/namespace.rb#L70) scope. Analyzing this query we noticed that: - It takes up to `1.2` seconds for namespaces with over `15k` projects. - It can't be analyzed with [ChatOps](chatops_on_gitlabcom.md), as it times out. diff --git a/doc/development/new_fe_guide/dependencies.md b/doc/development/new_fe_guide/dependencies.md index b58319c15ca..c8bc1b70aa9 100644 --- a/doc/development/new_fe_guide/dependencies.md +++ b/doc/development/new_fe_guide/dependencies.md @@ -1,5 +1,6 @@ --- redirect_to: '../fe_guide/dependencies.md' +remove_date: '2021-05-14' --- This document was moved to [another location](../fe_guide/dependencies.md). diff --git a/doc/development/new_fe_guide/development/performance.md b/doc/development/new_fe_guide/development/performance.md index 8ae503ec709..f34c407da84 100644 --- a/doc/development/new_fe_guide/development/performance.md +++ b/doc/development/new_fe_guide/development/performance.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w We have a performance dashboard available in one of our [Grafana instances](https://dashboards.gitlab.net/d/1EBTz3Dmz/sitespeed-page-summary?orgId=1). This dashboard automatically aggregates metric data from [sitespeed.io](https://www.sitespeed.io/) every 6 hours. These changes are displayed after a set number of pages are aggregated. These pages can be found inside a text file in the [`gitlab-build-images` repository](https://gitlab.com/gitlab-org/gitlab-build-images) called [`gitlab.txt`](https://gitlab.com/gitlab-org/gitlab-build-images/blob/master/scripts/gitlab.txt) -Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing URLs of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/company/team/) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes are pushed live on the next scheduled run after the changes are merged into `master`. +Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing URLs of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/company/team/) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes are pushed live on the next scheduled run after the changes are merged into `main`. There are 3 recommended high impact metrics to review on each page: diff --git a/doc/development/new_fe_guide/modules/dirty_submit.md b/doc/development/new_fe_guide/modules/dirty_submit.md index f9ef96c65dc..6e1062aa72e 100644 --- a/doc/development/new_fe_guide/modules/dirty_submit.md +++ b/doc/development/new_fe_guide/modules/dirty_submit.md @@ -14,7 +14,7 @@ Prevent submitting forms with no changes. Currently handles `input`, `textarea` and `select` elements. -Also, see [the code](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/javascripts/dirty_submit/) +Also, see [the code](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/dirty_submit/) within the GitLab project. ## Usage diff --git a/doc/development/packages.md b/doc/development/packages.md index 3727376d957..294cc528ad1 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -183,7 +183,7 @@ supports this case. There are project and group level permissions for `read_package`, `create_package`, and `destroy_package`. Each endpoint should -[authorize the requesting user](https://gitlab.com/gitlab-org/gitlab/blob/398fef1ca26ae2b2c3dc89750f6b20455a1e5507/ee/lib/api/conan_packages.rb) +[authorize the requesting user](https://gitlab.com/gitlab-org/gitlab/-/blob/398fef1ca26ae2b2c3dc89750f6b20455a1e5507/ee/lib/api/conan_packages.rb) against the project or group before continuing. #### Database and handling metadata @@ -219,7 +219,7 @@ demonstrates adding an instance-level endpoint for Conan to workhorse. You can a implemented in the same file. Once the route has been added, you must add an additional `/authorize` version of the upload endpoint to your API file. -[This example](https://gitlab.com/gitlab-org/gitlab/blob/398fef1ca26ae2b2c3dc89750f6b20455a1e5507/ee/lib/api/maven_packages.rb#L164) +[This example](https://gitlab.com/gitlab-org/gitlab/-/blob/398fef1ca26ae2b2c3dc89750f6b20455a1e5507/ee/lib/api/maven_packages.rb#L164) shows the additional endpoint added for Maven. The `/authorize` endpoint verifies and authorizes the request from workhorse, then the normal upload endpoint is implemented below, consuming the metadata that workhorse provides in order to create the package record. Workhorse provides a variety of file metadata such as type, size, and different checksum formats. @@ -276,7 +276,7 @@ features must be implemented when the feature flag is removed. - Background workers for extracting package metadata (if applicable) - Documentation (how to use the feature) - API Documentation (individual endpoints with curl examples) -- Seeding in [`db/fixtures/development/26_packages.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/db/fixtures/development/26_packages.rb) +- Seeding in [`db/fixtures/development/26_packages.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/db/fixtures/development/26_packages.rb) - Update the [runbook](https://gitlab.com/gitlab-com/runbooks/-/blob/31fb4959e89db25fddf865bc81734c222daf32dd/dashboards/stage-groups/package.dashboard.jsonnet#L74) for the Grafana charts - End-to-end feature tests for (at the minimum) publishing and installing a package diff --git a/doc/development/performance.md b/doc/development/performance.md index c6fe9f29b53..84b3a8f1092 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -283,8 +283,8 @@ Currently supported profiling targets are: - Sidekiq NOTE: -The Puma master process is not supported. Neither is Unicorn. -Sending SIGUSR2 to either of those triggers restarts. In the case of Puma, +The Puma master process is not supported. +Sending SIGUSR2 to it triggers restarts. In the case of Puma, take care to only send the signal to Puma workers. This can be done via `pkill -USR2 puma:`. The `:` distinguishes between `puma diff --git a/doc/development/permissions.md b/doc/development/permissions.md index 6ff0c6d5167..8c3600a30ba 100644 --- a/doc/development/permissions.md +++ b/doc/development/permissions.md @@ -78,7 +78,7 @@ is stored in the `project_authorizations` table. WARNING: Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), projects in personal namespace do not show owner (`50`) permission in -`project_authorizations` table. Note however that [`user.owned_projects`](https://gitlab.com/gitlab-org/gitlab/blob/0d63823b122b11abd2492bca47cc26858eee713d/app/models/user.rb#L906-916) +`project_authorizations` table. Note however that [`user.owned_projects`](https://gitlab.com/gitlab-org/gitlab/-/blob/0d63823b122b11abd2492bca47cc26858eee713d/app/models/user.rb#L906-916) is calculated properly. ### Confidential issues diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index 24f35bdab57..0dc1481f542 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -8,9 +8,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Pipelines for [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) and [`gitlab-org/gitlab-foss`](https://gitlab.com/gitlab-org/gitlab-foss) (as well as the `dev` instance's mirrors) are configured in the usual -[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml) +[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab-ci.yml) which itself includes files under -[`.gitlab/ci/`](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab/ci) +[`.gitlab/ci/`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/.gitlab/ci) for easier maintenance. We're striving to [dogfood](https://about.gitlab.com/handbook/engineering/#dogfooding) @@ -24,7 +24,7 @@ feature of the GitLab CI/CD. Pipelines are always created for the following scenarios: -- `master` branch, including on schedules, pushes, merges, and so on. +- `main` branch, including on schedules, pushes, merges, and so on. - Merge requests. - Tags. - Stable, `auto-deploy`, and security branches. @@ -37,7 +37,7 @@ Pipeline creation is also affected by the following CI/CD variables: No pipeline is created in any other cases (for example, when pushing a branch with no MR for it). -The source of truth for these workflow rules is defined in [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). +The source of truth for these workflow rules is defined in [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab-ci.yml). ### Pipelines for Merge Requests @@ -428,7 +428,7 @@ We are using a custom mapping between source file to test files, maintained in t As part of the objective to improve overall pipeline duration, we are experimenting with a minimal set of RSpec tests. The purpose of this experiment is to verify if we are able to run a minimal set of RSpec tests in a Merge Request pipeline, -without resulting in increased number of broken master. +without resulting in increased number of broken main branch. To identify the minimal set of tests needed, we use [Crystalball gem](https://github.com/toptal/crystalball) to create a test mapping. The test mapping contains a map of each source files to a list of test files which is dependent of the source file. @@ -484,14 +484,14 @@ Our test suite runs against PG12 as GitLab.com runs on PG12 and Our test suite is currently running against PG11, since GitLab.com still runs on PG11. We do run our test suite against PG11 on nightly scheduled pipelines as well as upon specific -database library changes in MRs and `master` pipelines (with the `rspec db-library-code pg11` job). +database library changes in MRs and `main` pipelines (with the `rspec db-library-code pg11` job). #### Current versions testing | Where? | PostgreSQL version | | ------ | ------------------ | | MRs | 12, 11 for DB library changes | -| `master` (non-scheduled pipelines) | 12, 11 for DB library changes | +| `main` (non-scheduled pipelines) | 12, 11 for DB library changes | | 2-hourly scheduled pipelines | 12, 11 for DB library changes | | `nightly` scheduled pipelines | 12, 11 | @@ -538,7 +538,7 @@ the `gitlab-org/gitlab-foss` project. ### Interruptible pipelines By default, all jobs are [interruptible](../ci/yaml/README.md#interruptible), except the -`dont-interrupt-me` job which runs automatically on `master`, and is `manual` +`dont-interrupt-me` job which runs automatically on `main`, and is `manual` otherwise. If you want a running pipeline to finish even if you push new commits to a merge @@ -549,7 +549,7 @@ request, be sure to start the `dont-interrupt-me` job before pushing. 1. All jobs must only pull caches by default. 1. All jobs must be able to pass with an empty cache. In other words, caches are only there to speed up jobs. 1. We currently have several different cache definitions defined in - [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml), + [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/global.gitlab-ci.yml), with fixed keys: - `.setup-test-env-cache` - `.rails-cache` @@ -561,12 +561,13 @@ request, be sure to start the `dont-interrupt-me` job before pushing. - `.assets-compile-cache` (the key includes `${NODE_ENV}` so it's actually two different caches). 1. These cache definitions are composed of [multiple atomic caches](../ci/yaml/README.md#multiple-caches). 1. Only 6 specific jobs, running in 2-hourly scheduled pipelines, are pushing (i.e. updating) to the caches: - - `update-setup-test-env-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - - `update-static-analysis-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - - `update-qa-cache`, defined in [`.gitlab/ci/qa.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/qa.gitlab-ci.yml). - - `update-assets-compile-production-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). - - `update-assets-compile-test-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). - - `update-yarn-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). + - `update-setup-test-env-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rails.gitlab-ci.yml). + - `update-gitaly-binaries-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rails.gitlab-ci.yml). + - `update-static-analysis-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rails.gitlab-ci.yml). + - `update-qa-cache`, defined in [`.gitlab/ci/qa.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/qa.gitlab-ci.yml). + - `update-assets-compile-production-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). + - `update-assets-compile-test-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). + - `update-yarn-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). 1. These jobs can also be forced to run in merge requests whose title include `UPDATE CACHE` (this can be useful to warm the caches in a MR that updates the cache keys). ### Artifacts strategy @@ -583,7 +584,7 @@ several reasons: - It significantly reduces load on the file server, as smaller deltas mean less time spent in `git pack-objects`. The pre-clone step works by using the `CI_PRE_CLONE_SCRIPT` variable -[defined by GitLab.com shared runners](../user/gitlab_com/index.md#pre-clone-script). +[defined by GitLab.com shared runners](../ci/runners/README.md#pre-clone-script). The `CI_PRE_CLONE_SCRIPT` is currently defined as a project CI/CD variable: @@ -608,7 +609,7 @@ The `CI_PRE_CLONE_SCRIPT` is currently defined as a project CI/CD variable: ``` The first step of the script downloads `gitlab-master.tar.gz` from -Google Cloud Storage. There is a [GitLab CI job named `cache-repo`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/cache-repo.gitlab-ci.yml#L5) +Google Cloud Storage. There is a [GitLab CI job named `cache-repo`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/cache-repo.gitlab-ci.yml#L5) that is responsible for keeping that archive up-to-date. Every two hours on a scheduled pipeline, it does the following: @@ -674,7 +675,7 @@ that is deployed in stage `review`. ### Default image -The default image is defined in [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). +The default image is defined in [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab-ci.yml). <!-- vale gitlab.Spelling = NO --> It includes Ruby, Go, Git, Git LFS, Chrome, Node, Yarn, PostgreSQL, and Graphics Magick. @@ -711,12 +712,12 @@ Docker Hub unless `${GITLAB_DEPENDENCY_PROXY}` is also defined there. In addition to the [predefined CI/CD variables](../ci/variables/predefined_variables.md), each pipeline includes default variables defined in -[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). +[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab-ci.yml). ### Common job definitions Most of the jobs [extend from a few CI definitions](../ci/yaml/README.md#extends) -defined in [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml) +defined in [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/global.gitlab-ci.yml) that are scoped to a single [configuration keyword](../ci/yaml/README.md#job-keywords). | Job definitions | Description | @@ -730,10 +731,10 @@ that are scoped to a single [configuration keyword](../ci/yaml/README.md#job-key | `.qa-cache` | Allows a job to use a default `cache` definition suitable for QA tasks. | | `.yarn-cache` | Allows a job to use a default `cache` definition suitable for frontend jobs that do a `yarn install`. | | `.assets-compile-cache` | Allows a job to use a default `cache` definition suitable for frontend jobs that compile assets. | -| `.use-pg11` | Allows a job to run the `postgres` 11 and `redis` services (see [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml) for the specific versions of the services). | -| `.use-pg11-ee` | Same as `.use-pg11` but also use an `elasticsearch` service (see [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml) for the specific version of the service). | -| `.use-pg12` | Allows a job to use the `postgres` 12 and `redis` services (see [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml) for the specific versions of the services). | -| `.use-pg12-ee` | Same as `.use-pg12` but also use an `elasticsearch` service (see [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml) for the specific version of the service). | +| `.use-pg11` | Allows a job to run the `postgres` 11 and `redis` services (see [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/global.gitlab-ci.yml) for the specific versions of the services). | +| `.use-pg11-ee` | Same as `.use-pg11` but also use an `elasticsearch` service (see [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/global.gitlab-ci.yml) for the specific version of the service). | +| `.use-pg12` | Allows a job to use the `postgres` 12 and `redis` services (see [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/global.gitlab-ci.yml) for the specific versions of the services). | +| `.use-pg12-ee` | Same as `.use-pg12` but also use an `elasticsearch` service (see [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/global.gitlab-ci.yml) for the specific version of the service). | | `.use-kaniko` | Allows a job to use the `kaniko` tool to build Docker images. | | `.as-if-foss` | Simulate the FOSS project by setting the `FOSS_ONLY='1'` CI/CD variable. | | `.use-docker-in-docker` | Allows a job to use Docker in Docker. | diff --git a/doc/development/polymorphic_associations.md b/doc/development/polymorphic_associations.md index b71e66c8671..f341255a7e1 100644 --- a/doc/development/polymorphic_associations.md +++ b/doc/development/polymorphic_associations.md @@ -62,19 +62,19 @@ AND source_id = 13083; ``` Here PostgreSQL can perform the query quite efficiently if both columns are -indexed, but as the query gets more complex it may not be able to use these -indexes efficiently. +indexed. As the query gets more complex, it may not be able to use these +indexes effectively. ## Mixed Responsibilities -Similar to functions and classes a table should have a single responsibility: +Similar to functions and classes, a table should have a single responsibility: storing data with a certain set of pre-defined columns. When using polymorphic -associations you are instead storing different types of data (possibly with +associations, you are storing different types of data (possibly with different columns set) in the same table. ## The Solution -Fortunately there is a very simple solution to these problems: use a +Fortunately, there is a solution to these problems: use a separate table for every type you would otherwise store in the same table. Using a separate table allows you to use everything a database may provide to ensure consistency and query data efficiently, without any additional application logic @@ -120,8 +120,8 @@ FROM pending_group_members WHERE group_id = 4 ``` -If you want to get both you can use a UNION, though you need to be explicit -about what columns you want to SELECT as otherwise the result set uses the +If you want to get both you can use a `UNION`, though you need to be explicit +about what columns you want to `SELECT` as otherwise the result set uses the columns of the first query. For example: ```sql diff --git a/doc/development/product_analytics/event_dictionary.md b/doc/development/product_analytics/event_dictionary.md index e8b8e0c4885..3931f0b35ab 100644 --- a/doc/development/product_analytics/event_dictionary.md +++ b/doc/development/product_analytics/event_dictionary.md @@ -1,8 +1,9 @@ --- redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-guide/' +remove_date: '2021-12-01' --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). -<!-- This redirect file can be deleted after December 1, 2021. --> +<!-- This redirect file can be deleted after 2021-12-01. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/product_analytics/index.md b/doc/development/product_analytics/index.md index e8b8e0c4885..3931f0b35ab 100644 --- a/doc/development/product_analytics/index.md +++ b/doc/development/product_analytics/index.md @@ -1,8 +1,9 @@ --- redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-guide/' +remove_date: '2021-12-01' --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). -<!-- This redirect file can be deleted after December 1, 2021. --> +<!-- This redirect file can be deleted after 2021-12-01. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/profiling.md b/doc/development/profiling.md index 81881a4d490..781138a6ade 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -49,7 +49,7 @@ ActiveRecord and ActionController log output to that logger. Further options are documented with the method source. ```ruby -Gitlab::Profiler.profile('/gitlab-org/gitlab-test', user: User.first, logger: Logger.new(STDOUT)) +Gitlab::Profiler.profile('/gitlab-org/gitlab-test', user: User.first, logger: Logger.new($stdout)) ``` There is also a RubyProf printer available: diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index 09efb70f279..66e980978bf 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Adding to the library -We strive to support the 2-4 most important metrics for each common system service that supports Prometheus. If you are looking for support for a particular exporter which has not yet been added to the library, additions can be made [to the `common_metrics.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/config/prometheus/common_metrics.yml) file. +We strive to support the 2-4 most important metrics for each common system service that supports Prometheus. If you are looking for support for a particular exporter which has not yet been added to the library, additions can be made [to the `common_metrics.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/prometheus/common_metrics.yml) file. ### Query identifier diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md index d662e6bbc54..402029164a7 100644 --- a/doc/development/pry_debugging.md +++ b/doc/development/pry_debugging.md @@ -12,8 +12,10 @@ To invoke the debugger, place `binding.pry` somewhere in your code. When the Ruby interpreter hits that code, execution stops, and you can type in commands to debug the state of the program. -When debugging code in another process like Puma or Sidekiq, you can use `binding.remote_pry`. -You can then connect to this session by running `pry-remote` from your terminal. +When debugging code in another process like Puma or Sidekiq, you can use `binding.pry_shell`. +You can then connect to this session by using the [pry-shell](https://github.com/meinac/pry-shell) executable. +You can watch [this video](https://www.youtube.com/watch?v=Lzs_PL_BySo), for more information about +how to use the `pry-shell`. ## `byebug` vs `binding.pry` diff --git a/doc/development/query_recorder.md b/doc/development/query_recorder.md index 3cc7b140e89..46866f67f68 100644 --- a/doc/development/query_recorder.md +++ b/doc/development/query_recorder.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w QueryRecorder is a tool for detecting the [N+1 queries problem](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations) from tests. -> Implemented in [spec/support/query_recorder.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/support/helpers/query_recorder.rb) via [9c623e3e](https://gitlab.com/gitlab-org/gitlab-foss/commit/9c623e3e5d7434f2e30f7c389d13e5af4ede770a) +> Implemented in [spec/support/query_recorder.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/helpers/query_recorder.rb) via [9c623e3e](https://gitlab.com/gitlab-org/gitlab-foss/commit/9c623e3e5d7434f2e30f7c389d13e5af4ede770a) As a rule, merge requests [should not increase query counts](merge_request_performance_guidelines.md#query-counts). If you find yourself adding something like `.includes(:author, :assignee)` to avoid having `N+1` queries, consider using QueryRecorder to enforce this with a test. Without this, a new feature which causes an additional model to be accessed can silently reintroduce the problem. diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index c6c3d39c57f..8d20c2b738e 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -236,7 +236,7 @@ task, then check the dimensions of the new sprite sheet and update the ## Update project templates Starting a project from a template needs this project to be exported. On a -up to date master branch run: +up to date main branch run: ```shell gdk start @@ -247,7 +247,7 @@ git commit git push -u origin update-project-templates ``` -Now create a merge request and merge that to master. +Now create a merge request and merge that to main. ## Generate route lists @@ -263,7 +263,7 @@ RESTful API verbs. For the Rails controllers, run: ```shell -bundle exec rake routes +bundle exec rails routes ``` Since these take some time to create, it's often helpful to save the output to diff --git a/doc/development/reactive_caching.md b/doc/development/reactive_caching.md index 0223f5d91d6..b6878ee48f1 100644 --- a/doc/development/reactive_caching.md +++ b/doc/development/reactive_caching.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # `ReactiveCaching` -> This doc refers to [`reactive_caching.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/reactive_caching.rb). +> This doc refers to [`reactive_caching.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/concerns/reactive_caching.rb). The `ReactiveCaching` concern is used for fetching some data in the background and storing it in the Rails cache, keeping it up-to-date for as long as it is being requested. If the diff --git a/doc/development/real_time.md b/doc/development/real_time.md new file mode 100644 index 00000000000..df725a36a93 --- /dev/null +++ b/doc/development/real_time.md @@ -0,0 +1,97 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Real-Time Features + +This guide contains instructions on how to safely roll out new real-time +features. + +Real-time features are implemented using GraphQL Subscriptions. +[Developer documentation](api_graphql_styleguide.md#subscriptions) is available. + +WebSockets are a relatively new technology at GitLab, and supporting them at +scale introduces some challenges. For that reason, new features should be rolled +out using the instructions below. + +## Reuse an existing WebSocket connection + +Features reusing an existing connection incur minimal risk. Feature flag rollout +is recommended in order to give more control to self-hosting customers. However, +it is not necessary to roll out in percentages, or to estimate new connections for +GitLab.com. + +## Introduce a new WebSocket connection + +Any change that introduces a WebSocket connection to part of the GitLab application +incurs some scalability risk, both to nodes responsible for maintaining open +connections and on downstream services; such as Redis and the primary database. + +### Estimate peak connections + +The first real-time feature to be fully enabled on GitLab.com was +[real-time assignees](https://gitlab.com/gitlab-org/gitlab/-/issues/17589). By comparing +peak throughput to the issue page against peak simultaneous WebSocket connections it is +possible to crudely estimate that each 1 request per second adds +approximately 4200 WebSocket connections. + +To understand the impact a new feature might have, sum the peak throughput (RPS) +to the pages it originates from (`n`) and apply the formula: + +```ruby +(n * 4200) / peak_active_connections +``` + +Current active connections are visible on +[this Grafana chart](https://dashboards.gitlab.net/d/websockets-main/websockets-overview?viewPanel=1357460996&orgId=1). + +This calculation is crude, and should be revised as new features are +deployed. It yields a rough estimate of the capacity that must be +supported, as a proportion of existing capacity. + +### Graduated roll-out + +New capacity may need to be provisioned to support your changes, depending on +current saturation and the proportion of new connections required. While +Kubernetes makes this relatively easy in most cases, there remains a risk to +downstream services. + +To mitigate this, ensure that the code establishing the new WebSocket connection +is feature flagged and defaulted to `off`. A careful, percentage-based roll-out +of the feature flag ensures that effects can be observed on the [WebSocket +dashboard](https://dashboards.gitlab.net/d/websockets-main/websockets-overview?orgId=1) + +1. Create a + [feature flag roll-out](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20Flag%20Roll%20Out.md) + issue. +1. Add the estimated new connections required under the **What are we expecting to happen** section. +1. Copy in a member of the Plan and Scalability teams to estimate a percentage-based + roll-out plan. + +## Backward compatibility + +For the duration of the feature flag roll-out and indefinitely thereafter, +real-time features must be backward-compatible, or at least degrade +gracefully. Not all customers have Action Cable enabled, and further work +needs to be done before Action Cable can be enabled by default. + +Making real-time a requirement represents a breaking change, so the next +opportunity to do this is version 15.0. + +## Enable Real-Time by default + +Mounting the Action Cable library adds minimal memory footprint. However, +serving WebSocket requests introduces additional memory requirements. For this +reason, enabling Action Cable by default requires additional work; perhaps +to reduce overall memory usage, including a known issue with Workhorse, but at +least to revise Reference Architectures. + +## Real-time infrastructure on GitLab.com + +On GitLab.com, WebSocket connections are served from dedicated infrastructure, +entirely separate from the regular Web fleet and deployed with Kubernetes. This +limits risk to nodes handling requests but not to shared services. For more +information on the WebSockets Kubernetes deployment see +[this epic](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/355). diff --git a/doc/development/redis.md b/doc/development/redis.md index c7111db0cdc..893fe1dcbcd 100644 --- a/doc/development/redis.md +++ b/doc/development/redis.md @@ -18,8 +18,9 @@ Redis instance. On GitLab.com, we use [separate Redis instances](../administration/redis/replication_and_failover.md#running-multiple-redis-clusters). -(We do not currently use [ActionCable on -GitLab.com](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/228)). +See the [Redis SRE guide](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/redis/redis-survival-guide-for-sres.md) +for more details on our setup. +We do not currently use [ActionCable on GitLab.com](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/228). Every application process is configured to use the same Redis servers, so they can be used for inter-process communication in cases where [PostgreSQL](sql.md) @@ -158,7 +159,7 @@ following is true: ### `Gitlab::Redis::{Cache,SharedState,Queues}` These classes wrap the Redis instances (using -[`Gitlab::Redis::Wrapper`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/redis/wrapper.rb)) +[`Gitlab::Redis::Wrapper`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/redis/wrapper.rb)) to make it convenient to work with them directly. The typical use is to call `.with` on the class, which takes a block that yields the Redis connection. For example: @@ -174,7 +175,7 @@ Gitlab::Redis::Cache.with { |redis| redis.sismember(key, value) } ### `Gitlab::Redis::Boolean` In Redis, every value is a string. -[`Gitlab::Redis::Boolean`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/redis/boolean.rb) +[`Gitlab::Redis::Boolean`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/redis/boolean.rb) makes sure that booleans are encoded and decoded consistently. ### `Gitlab::Redis::HLL` @@ -187,19 +188,19 @@ elements with low memory usage. (In addition to the `PFCOUNT` documentation, Thoughtbot's article on [HyperLogLogs in Redis](https://thoughtbot.com/blog/hyperloglogs-in-redis) provides a good background here.) -[`Gitlab::Redis::HLL`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/redis/hll.rb) +[`Gitlab::Redis::HLL`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/redis/hll.rb) provides a convenient interface for adding and counting values in HyperLogLogs. ### `Gitlab::SetCache` For cases where we need to efficiently check the whether an item is in a group of items, we can use a Redis set. -[`Gitlab::SetCache`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/set_cache.rb) +[`Gitlab::SetCache`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/set_cache.rb) provides an `#include?` method that uses the [`SISMEMBER`](https://redis.io/commands/sismember) command, as well as `#read` to fetch all entries in the set. This is used by the -[`RepositorySetCache`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/repository_set_cache.rb) +[`RepositorySetCache`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/repository_set_cache.rb) to provide a convenient way to use sets to cache repository data like branch names. diff --git a/doc/development/reference_processing.md b/doc/development/reference_processing.md index 23c0861081d..2fd0ce51b39 100644 --- a/doc/development/reference_processing.md +++ b/doc/development/reference_processing.md @@ -37,18 +37,18 @@ the tools that identify short-code and URI references from markup documents and transform them into structured links to the resources they represent. For example, the class -[`Banzai::Filter::IssueReferenceFilter`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/filter/issue_reference_filter.rb) +[`Banzai::Filter::IssueReferenceFilter`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/filter/issue_reference_filter.rb) is responsible for handling references to issues, such as `gitlab-org/gitlab#123` and `https://gitlab.com/gitlab-org/gitlab/-/issues/200048`. All reference filters are instances of [`HTML::Pipeline::Filter`](https://www.rubydoc.info/github/jch/html-pipeline/HTML/Pipeline/Filter), -and inherit (often indirectly) from [`Banzai::Filter::ReferenceFilter`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/filter/reference_filter.rb). +and inherit (often indirectly) from [`Banzai::Filter::ReferenceFilter`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/filter/reference_filter.rb). `HTML::Pipeline::Filter` has a simple interface consisting of `#call`, a void method that mutates the current document. `ReferenceFilter` provides methods that make defining suitable `#call` methods easier. Most reference filters however do not inherit from either of these classes directly, but from -[`AbstractReferenceFilter`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/filter/abstract_reference_filter.rb), +[`AbstractReferenceFilter`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/filter/abstract_reference_filter.rb), which provides a higher-level interface. Subclasses of `AbstractReferenceFilter` generally do not override `#call`; instead, @@ -65,7 +65,7 @@ a minimum implementation of `AbstractReferenceFilter` should define: This is used to: - Find the regular expressions used to find references. The class should - include [`Referable`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/referable.rb) + include [`Referable`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/concerns/referable.rb) and thus define two regular expressions: `.link_reference_pattern` and `.reference_pattern`, both of which should contain a named capture group named the value of `ReferenceFilter.object_sym`. @@ -75,7 +75,7 @@ a minimum implementation of `AbstractReferenceFilter` should define: - `.parse_symbol(string)`: parse the text value to an object identifier (`#to_i` by default). - `#record_identifier(record)`: the inverse of `.parse_symbol`, that is, transform a domain object to an identifier (`#id` by default). - `#url_for_object(object, parent_object)`: generate the URL for a domain object. -- `#find_object(parent_object, id)`: given the parent (usually a [`Project`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/project.rb)) +- `#find_object(parent_object, id)`: given the parent (usually a [`Project`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/project.rb)) and an identifier, find the object. For example, this in a reference filter for merge requests, this might be `project.merge_requests.where(iid: iid)`. @@ -113,7 +113,7 @@ method: `#parent_records(parent, set_of_identifiers)`, which must return an enumerable of domain objects. This allows such classes to define `#find_object` (as -[`IssuableReferenceFilter`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/filter/issuable_reference_filter.rb) +[`IssuableReferenceFilter`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/filter/issuable_reference_filter.rb) does) as: ```ruby @@ -160,7 +160,7 @@ these sensitive pieces of data. This is what `ReferenceParser` classes do. A reference parser is linked to the object that it handles by the link advertising this relationship in the `data-reference-type` attribute (set by the reference filter). This is used by the -[`ReferenceRedactor`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/reference_redactor.rb) +[`ReferenceRedactor`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/reference_redactor.rb) to compute which nodes should be visible to users: ```ruby @@ -189,7 +189,7 @@ each reference parser must: - Be placed in the `Banzai::ReferenceParser` namespace. - Implement the `.nodes_visible_to_user(user, nodes)` method. -In practice, all reference parsers inherit from [`BaseParser`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/reference_parser/base_parser.rb), and are implemented by defining: +In practice, all reference parsers inherit from [`BaseParser`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/reference_parser/base_parser.rb), and are implemented by defining: - `.reference_type`, which should equal `ReferenceFilter.reference_type`. - And by implementing one or more of: diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index 648f7104814..1e200e1f520 100644 --- a/doc/development/reusing_abstractions.md +++ b/doc/development/reusing_abstractions.md @@ -143,7 +143,7 @@ Service classes usually have an `execute` method, which can return a In a successful case: -``` ruby +```ruby response = ServiceResponse.success(message: 'Branch was deleted') response.success? # => true @@ -154,7 +154,7 @@ response.message # => 'Branch was deleted' In a failed case: -``` ruby +```ruby response = ServiceResponse.error(message: 'Unsupported operation') response.success? # => false @@ -165,7 +165,7 @@ response.message # => 'Unsupported operation' An additional payload can also be attached: -``` ruby +```ruby response = ServiceResponse.success(payload: { issue: issue }) response.payload[:issue] # => issue diff --git a/doc/development/routing.md b/doc/development/routing.md index 2c2f6b2a558..8fca9b00157 100644 --- a/doc/development/routing.md +++ b/doc/development/routing.md @@ -69,6 +69,18 @@ gitlab-org/gitlab/-/settings/repository gitlab-org/serverless/runtimes/-/settings/repository ``` +## Changing existing routes + +Don't change a URL to an existing page, unless it's necessary. If you must make a change, +make it unnoticeable for users, because we don't want them to receive `404 Not Found` +if we can avoid it. This table should help: + +| URL description | Example | What to do | +|---|---|---| +| Can be used in scripts and automation | `snippet#raw` | Support both an old and new URL for one major release. Then, support a redirect from an old URL to a new URL for another major release. | +| Likely to be saved or shared | `issue#show` | Add a redirect from an old URL to a new URL until the next major release. | +| Limited use, unlikely to be shared | `admin#labels` | No extra steps required. | + ## Migrating unscoped routes Currently, the majority of routes are placed under the `/-/` scope. However, diff --git a/doc/development/scalability.md b/doc/development/scalability.md index 8ee6e57e4d1..b260618c220 100644 --- a/doc/development/scalability.md +++ b/doc/development/scalability.md @@ -24,7 +24,7 @@ users. We discuss each component below. The PostgreSQL database holds all metadata for projects, issues, merge requests, users, etc. The schema is managed by the Rails application -[db/structure.sql](https://gitlab.com/gitlab-org/gitlab/blob/master/db/structure.sql). +[db/structure.sql](https://gitlab.com/gitlab-org/gitlab/-/blob/master/db/structure.sql). GitLab Web/API servers and Sidekiq nodes talk directly to the database by using a Rails object relational model (ORM). Most SQL queries are accessed by using this @@ -119,7 +119,7 @@ that backup, the database can apply the WAL logs in order until the database has reached the target time. On GitLab.com, Consul and Patroni work together to coordinate failovers with -the read replicas. [Omnibus ships with both repmgr and Patroni](../administration/postgresql/replication_and_failover.md). +the read replicas. [Omnibus ships with Patroni](../administration/postgresql/replication_and_failover.md). #### Load-balancing @@ -248,9 +248,9 @@ lifting of many activities, including: - Processing CI builds and pipelines. The full list of jobs can be found in the -[`app/workers`](https://gitlab.com/gitlab-org/gitlab/tree/master/app/workers) +[`app/workers`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/workers) and -[`ee/app/workers`](https://gitlab.com/gitlab-org/gitlab/tree/master/ee/app/workers) +[`ee/app/workers`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/app/workers) directories in the GitLab codebase. #### Runaway Queues diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index 62cc2543fc4..74f65034383 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -129,7 +129,7 @@ way that increases execution time by several orders of magnitude. ### Impact -The resource, for example Unicorn, Puma, or Sidekiq, can be made to hang as it takes +The resource, for example Puma, or Sidekiq, can be made to hang as it takes a long time to evaluate the bad regex match. The evaluation time may require manual termination of the resource. @@ -384,7 +384,7 @@ References: ### Select examples of past XSS issues affecting GitLab - [Stored XSS in user status](https://gitlab.com/gitlab-org/gitlab-foss/issues/55320) -- [XSS vulnerability on custom project templates form](https://gitlab.com/gitlab-org/gitlab/issues/197302) +- [XSS vulnerability on custom project templates form](https://gitlab.com/gitlab-org/gitlab/-/issues/197302) - [Stored XSS in branch names](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55320) - [Stored XSS in merge request pages](https://gitlab.com/gitlab-org/gitlab/-/issues/35096) diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index 82b6a54540f..c87870b088c 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -154,6 +154,12 @@ A good example of that would be a cache expiration worker. A job scheduled for an idempotent worker is [deduplicated](#deduplication) when an unstarted job with the same arguments is already in the queue. +WARNING: +For [data consistency jobs](#job-data-consistency), the deduplication is not compatible with the +`data_consistency` attribute set to `:sticky` or `:delayed`. +The reason for this is that deduplication always takes into account the latest binary replication pointer into account, not the first one. +There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/325291) to improve this. + ### Ensuring a worker is idempotent Make sure the worker tests pass using the following shared example: @@ -456,6 +462,68 @@ If we expect an increase of **less than 5%**, then no further action is needed. Otherwise, please ping `@gitlab-org/scalability` on the merge request and ask for a review. +## Job data consistency + +In order to utilize [Sidekiq read-only database replicas capabilities](../administration/database_load_balancing.md#enable-the-load-balancer-for-sidekiq), +set the `data_consistency` attribute of the job to `:always`, `:sticky`, or `:delayed`. + +| **Data Consistency** | **Description** | +|--------------|-----------------------------| +| `:always` | The job is required to use the primary database (default). | +| `:sticky` | The job uses a replica as long as possible. It switches to primary either on write or long replication lag. It should be used on jobs that require to be executed as fast as possible. | +| `:delayed` | The job always uses replica, but switches to primary on write. The job is delayed if there's a long replication lag. If the replica is not up-to-date with the next retry, it switches to the primary. It should be used on jobs where we are fine to delay the execution of a given job due to their importance such as expire caches, execute hooks, etc. | + +To set a data consistency for a job, use the `data_consistency` class method: + +```ruby +class DelayedWorker + include ApplicationWorker + + data_consistency :delayed + + # ... +end +``` + +For [idempotent jobs](#idempotent-jobs), the deduplication is not compatible with the +`data_consistency` attribute set to `:sticky` or `:delayed`. +The reason for this is that deduplication always takes into account the latest binary replication pointer into account, not the first one. +There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/325291) to improve this. + +### `feature_flag` property + +The `feature_flag` property allows you to toggle a job's `data_consistency`, +which permits you to safely toggle load balancing capabilities for a specific job. +When `feature_flag` is disabled, the job defaults to `:always`, which means that the job will always use the primary database. + +The `feature_flag` property does not allow the use of +[feature gates based on actors](../development/feature_flags/index.md). +This means that the feature flag cannot be toggled only for particular +projects, groups, or users, but instead, you can safely use [percentage of time rollout](../development/feature_flags/index.md). +Note that since we check the feature flag on both Sidekiq client and server, rolling out a 10% of the time, +will likely results in 1% (0.1 [from client]*0.1 [from server]) of effective jobs using replicas. + +Example: + +```ruby +class DelayedWorker + include ApplicationWorker + + data_consistency :delayed, feature_flag: :load_balancing_for_delayed_worker + + # ... +end +``` + +### Delayed job execution + +Scheduling workers that utilize [Sidekiq read-only database replicas capabilities](#job-data-consistency), +(workers with `data_consistency` attribute set to `:sticky` or `:delayed`), +by calling `SomeWorker.perform_async` results in a worker performing in the future (1 second in the future). + +This way, the replica has a chance to catch up, and the job will likely use the replica. +For workers with `data_consistency` set to `:delayed`, it can also reduce the number of retried jobs. + ## Jobs with External Dependencies Most background jobs in the GitLab application communicate with other GitLab diff --git a/doc/development/single_table_inheritance.md b/doc/development/single_table_inheritance.md index 6b35d9f71da..aa4fe540b0d 100644 --- a/doc/development/single_table_inheritance.md +++ b/doc/development/single_table_inheritance.md @@ -22,3 +22,42 @@ The solution is very simple: just use a separate table for every type you'd otherwise store in the same table. For example, instead of having a `keys` table with `type` set to either `Key` or `DeployKey` you'd have two separate tables: `keys` and `deploy_keys`. + +## In migrations + +Whenever a model is used in a migration, single table inheritance should be disabled. +Due to the way Rails loads associations (even in migrations), failing to disable STI +could result in loading unexpected code or associations which may cause unintended +side effects or failures during upgrades. + +```ruby +class SomeMigration < ActiveRecord::Migration[6.0] + class Services < ActiveRecord::Base + self.table_name = 'services' + self.inheritance_column = :_type_disabled + end + + def up + ... +``` + +If nothing needs to be added to the model other than disabling STI or `EachBatch`, +use the helper `define_batchable_model` instead of defining the class. +This ensures that the migration loads the columns for the migration in isolation, +and the helper disables STI by default. + +```ruby +class EnqueueSomeBackgroundMigration < ActiveRecord::Migration[6.0] + disable_ddl_transaction! + + def up + define_batchable_model('services').select(:id).in_batches do |relation| + jobs = relation.pluck(:id).map do |id| + ['ExtractServicesUrl', [id]] + end + + BackgroundMigrationWorker.bulk_perform_async(jobs) + end + end + ... +``` diff --git a/doc/development/snowplow.md b/doc/development/snowplow.md index b5d3be5b2dd..aa1733fd42a 100644 --- a/doc/development/snowplow.md +++ b/doc/development/snowplow.md @@ -1,6 +1,8 @@ --- redirect_to: 'snowplow/index.md' +remove_date: '2021-06-30' --- This document was moved to [another location](snowplow/index.md). + <!-- This redirect file can be deleted after 2021-06-31. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/snowplow/index.md b/doc/development/snowplow/index.md index ece72dbbf03..0bf4b9356e7 100644 --- a/doc/development/snowplow/index.md +++ b/doc/development/snowplow/index.md @@ -24,7 +24,7 @@ More useful links: Snowplow is an enterprise-grade marketing and Product Intelligence platform which helps track the way users engage with our website and application. -[Snowplow](https://github.com/snowplow/snowplow) consists of the following loosely-coupled sub-systems: +[Snowplow](https://snowplowanalytics.com) consists of the following loosely-coupled sub-systems: - **Trackers** fire Snowplow events. Snowplow has 12 trackers, covering web, mobile, desktop, server, and IoT. - **Collectors** receive Snowplow events from trackers. We have three different event collectors, synchronizing events either to Amazon S3, Apache Kafka, or Amazon Kinesis. @@ -35,35 +35,38 @@ Snowplow is an enterprise-grade marketing and Product Intelligence platform whic  -## Snowplow schema +### Useful links -We have many definitions of Snowplow's schema. We have an active issue to [standardize this schema](https://gitlab.com/gitlab-org/gitlab/-/issues/207930) including the following definitions: +- [Understanding the structure of Snowplow data](https://docs.snowplowanalytics.com/docs/understanding-your-pipeline/canonical-event/) +- [Our Iglu schema registry](https://gitlab.com/gitlab-org/iglu) +- [List of events used in our codebase (Event Dictionary)](dictionary.md) -- Frontend and backend taxonomy as listed below -- [Structured event taxonomy](#structured-event-taxonomy) -- [Self describing events](https://github.com/snowplow/snowplow/wiki/Custom-events#self-describing-events) -- [Iglu schema](https://gitlab.com/gitlab-org/iglu/) -- [Snowplow authored events](https://github.com/snowplow/snowplow/wiki/Snowplow-authored-events) - -## Enabling Snowplow +## Enable Snowplow tracking Tracking can be enabled at: - The instance level, which enables tracking on both the frontend and backend layers. -- User level, though user tracking can be disabled on a per-user basis. GitLab tracking respects the [Do Not Track](https://www.eff.org/issues/do-not-track) standard, so any user who has enabled the Do Not Track option in their browser is not tracked at a user level. +- The user level, though user tracking can be disabled on a per-user basis. + GitLab respects the [Do Not Track](https://www.eff.org/issues/do-not-track) standard, so any user who has enabled the Do Not Track option in their browser is not tracked at a user level. + +Snowplow tracking is enabled on GitLab.com, and we use it for most of our tracking strategy. + +To enable Snowplow tracking on a self-managed instance: -We use Snowplow for the majority of our tracking strategy and it is enabled on GitLab.com. On a self-managed instance, Snowplow can be enabled by navigating to: +1. On the top bar, select **Menu >** **{admin}** **Admin**, then select **Settings > General**. + Alternatively, go to `admin/application_settings/general` in your browser. -- **Admin Area > Settings > General** in the UI. -- `admin/application_settings/integrations` in your browser. +1. Expand **Snowplow**. -Example configuration: +1. Select **Enable snowplow tracking** and enter your Snowplow configuration information. For example: -| Name | Value | -|---------------|-------------------------------| -| Collector | `your-snowplow-collector.net` | -| Site ID | `gitlab` | -| Cookie domain | `.your-gitlab-instance.com` | + | Name | Value | + |--------------------|-------------------------------| + | Collector hostname | `your-snowplow-collector.net` | + | App ID | `gitlab` | + | Cookie domain | `.your-gitlab-instance.com` | + +1. Select **Save changes**. ## Snowplow request flow @@ -155,13 +158,13 @@ Snowplow JS adds many [web-specific parameters](https://docs.snowplowanalytics.c ## Implementing Snowplow JS (Frontend) tracking -GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://github.com/snowplow/snowplow/wiki/javascript-tracker) for tracking custom events. The simplest way to use it is to add `data-` attributes to clickable elements and dropdowns. There is also a Vue mixin (exposing a `track` method), and the static method `Tracking.event`. Each of these requires at minimum a `category` and an `action`. Additional data can be provided that adheres to our [Structured event taxonomy](#structured-event-taxonomy). +GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers) for tracking custom events. The simplest way to use it is to add `data-` attributes to clickable elements and dropdowns. There is also a Vue mixin (exposing a `track` method), and the static method `Tracking.event`. Each of these requires at minimum a `category` and an `action`. You can provide additional [Structured event taxonomy](#structured-event-taxonomy) properties along with an `extra` object that accepts key-value pairs. | field | type | default value | description | |:-----------|:-------|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `category` | string | `document.body.dataset.page` | Page or subsection of a page that events are being captured within. | | `action` | string | generic | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. | -| `data` | object | `{}` | Additional data such as `label`, `property`, `value`, and `context` as described in our [Structured event taxonomy](#structured-event-taxonomy). | +| `data` | object | `{}` | Additional data such as `label`, `property`, `value`, `context` (as described in our [Structured event taxonomy](#structured-event-taxonomy)), and `extra` (key-value pairs object). | ### Usage recommendations @@ -171,7 +174,7 @@ GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tra ### Tracking with data attributes -When working within HAML (or Vue templates) we can add `data-track-*` attributes to elements of interest. All elements that have a `data-track-action` attribute automatically have event tracking bound on clicks. +When working within HAML (or Vue templates) we can add `data-track-*` attributes to elements of interest. All elements that have a `data-track-action` attribute automatically have event tracking bound on clicks. You can provide extra data as a valid JSON string using `data-track-extra`. Below is an example of `data-track-*` attributes assigned to a button: @@ -184,6 +187,7 @@ Below is an example of `data-track-*` attributes assigned to a button: data-track-action="click_button" data-track-label="template_preview" data-track-property="my-template" + data-track-extra='{ "template_variant": "primary" }' /> ``` @@ -196,7 +200,8 @@ Below is a list of supported `data-track-*` attributes: | `data-track-action` | true | Action the user is taking. Clicks must be prepended with `click` and activations must be prepended with `activate`. For example, focusing a form field would be `activate_form_input` and clicking a button would be `click_button`. Replaces `data-track-event`, which was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290962) in GitLab 13.11. | | `data-track-label` | false | The `label` as described in our [Structured event taxonomy](#structured-event-taxonomy). | | `data-track-property` | false | The `property` as described in our [Structured event taxonomy](#structured-event-taxonomy). | -| `data-track-value` | false | The `value` as described in our [Structured event taxonomy](#structured-event-taxonomy). If omitted, this is the element's `value` property or an empty string. For checkboxes, the default value is the element's checked attribute or `false` when unchecked. | +| `data-track-value` | false | The `value` as described in our [Structured event taxonomy](#structured-event-taxonomy). If omitted, this is the element's `value` property or `undefined`. For checkboxes, the default value is the element's checked attribute or `0` when unchecked. | +| `data-track-extra` | false | A key-value pairs object passed as a valid JSON string. This is added to the `extra` property in our [`gitlab_standard`](#gitlab_standard) schema. | | `data-track-context` | false | The `context` as described in our [Structured event taxonomy](#structured-event-taxonomy). | #### Available helpers @@ -287,6 +292,7 @@ export default { // category: '', // property: '', // value: '', + // extra: {}, }, }; }, @@ -357,6 +363,10 @@ button.addEventListener('click', () => { Tracking.event('dashboard:projects:index', 'click_button', { label: 'create_from_template', property: 'template_preview', + extra: { + templateVariant: 'primary', + valid: 1, + }, }); }); ``` @@ -381,6 +391,50 @@ describe('MyTracking', () => { expect(Tracking.event).toHaveBeenCalledWith(undefined, 'click_button', { label: 'create_from_template', property: 'template_preview', + extra: { + templateVariant: 'primary', + valid: true, + }, + }); + }); +}); +``` + +### Form tracking + +You can enable Snowplow automatic [form tracking](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/javascript-tracker/javascript-tracker-v2/tracking-specific-events/#form-tracking) by calling `Tracking.enableFormTracking` (after the DOM is ready) and providing a `config` object that includes at least one of the following elements: + +- `forms`: determines which forms are tracked, and are identified by the CSS class name. +- `fields`: determines which fields inside the tracked forms are tracked, and are identified by the field `name`. + +An optional list of contexts can be provided as the second argument. +Note that our [`gitlab_standard`](#gitlab_standard) schema is excluded from these events. + +```javascript +Tracking.enableFormTracking({ + forms: { allow: ['sign-in-form', 'password-recovery-form'] }, + fields: { allow: ['terms_and_conditions', 'newsletter_agreement'] }, +}); +``` + +#### Testing example + +```javascript +import Tracking from '~/tracking'; + +describe('MyFormTracking', () => { + let formTrackingSpy; + + beforeEach(() => { + formTrackingSpy = jest + .spyOn(Tracking, 'enableFormTracking') + .mockImplementation(() => null); + }); + + it('initialized with the correct configuration', () => { + expect(formTrackingSpy).toHaveBeenCalledWith({ + forms: { allow: ['sign-in-form', 'password-recovery-form'] }, + fields: { allow: ['terms_and_conditions', 'newsletter_agreement'] }, }); }); }); @@ -388,7 +442,7 @@ describe('MyTracking', () => { ## Implementing Snowplow Ruby (Backend) tracking -GitLab provides `Gitlab::Tracking`, an interface that wraps the [Snowplow Ruby Tracker](https://github.com/snowplow/snowplow/wiki/ruby-tracker) for tracking custom events. +GitLab provides `Gitlab::Tracking`, an interface that wraps the [Snowplow Ruby Tracker](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker) for tracking custom events. Custom event tracking and instrumentation can be added by directly calling the `GitLab::Tracking.event` class method, which accepts the following arguments: @@ -444,7 +498,15 @@ There are several tools for developing and testing Snowplow Event **{check-circle}** Available, **{status_preparing}** In progress, **{dotted-circle}** Not Planned -### Snowplow Analytics Debugger Chrome Extension +### Test frontend events + +To test frontend events in development: + +- [Enable Snowplow tracking in the Admin Area](#enable-snowplow-tracking). +- Turn off any ad blockers that would prevent Snowplow JS from loading in your environment. +- Turn off "Do Not Track" (DNT) in your browser. + +#### Snowplow Analytics Debugger Chrome Extension Snowplow Analytics Debugger is a browser extension for testing frontend events. This works on production, staging and local development environments. @@ -452,7 +514,7 @@ Snowplow Analytics Debugger is a browser extension for testing frontend events. 1. Open Chrome DevTools to the Snowplow Analytics Debugger tab. 1. Learn more at [Igloo Analytics](https://www.iglooanalytics.com/blog/snowplow-analytics-debugger-chrome-extension.html). -### Snowplow Inspector Chrome Extension +#### Snowplow Inspector Chrome Extension Snowplow Inspector Chrome Extension is a browser extension for testing frontend events. This works on production, staging and local development environments. @@ -565,6 +627,20 @@ Snowplow Mini can be used for testing frontend and backend events on a productio For GitLab.com, we're setting up a [QA and Testing environment](https://gitlab.com/gitlab-org/telemetry/-/issues/266) using Snowplow Mini. +### Troubleshooting + +To control content security policy warnings when using an external host, you can allow or disallow them by modifying `config/gitlab.yml`. To allow them, add the relevant host for `connect_src`. For example, for `https://snowplow.trx.gitlab.net`: + +```yaml +development: + <<: *base + gitlab: + content_security_policy: + enabled: true + directives: + connect_src: "'self' http://localhost:* http://127.0.0.1:* ws://localhost:* wss://localhost:* ws://127.0.0.1:* https://snowplow.trx.gitlab.net/" +``` + ## Snowplow Schemas ### `gitlab_standard` diff --git a/doc/development/stage_group_dashboards.md b/doc/development/stage_group_dashboards.md index 44c738092ac..277c12fc938 100644 --- a/doc/development/stage_group_dashboards.md +++ b/doc/development/stage_group_dashboards.md @@ -52,6 +52,26 @@ component has 2 indicators: 1. [Apdex](https://en.wikipedia.org/wiki/Apdex): The rate of operations that performed adequately. + + The threshold for 'performed adequately' is stored in our [metrics + catalog](https://gitlab.com/gitlab-com/runbooks/-/tree/master/metrics-catalog) + and depends on the service in question. For the Puma (Rails) + component of the + [API](https://gitlab.com/gitlab-com/runbooks/-/blob/f22f40b2c2eab37d85e23ccac45e658b2c914445/metrics-catalog/services/api.jsonnet#L127), + [Git](https://gitlab.com/gitlab-com/runbooks/-/blob/f22f40b2c2eab37d85e23ccac45e658b2c914445/metrics-catalog/services/git.jsonnet#L216), + and + [Web](https://gitlab.com/gitlab-com/runbooks/-/blob/f22f40b2c2eab37d85e23ccac45e658b2c914445/metrics-catalog/services/web.jsonnet#L154) + services, that threshold is **1 second**. + + For Sidekiq job execution, the threshold depends on the [job + urgency](sidekiq_style_guide.md#job-urgency). It is + [currently](https://gitlab.com/gitlab-com/runbooks/-/blob/f22f40b2c2eab37d85e23ccac45e658b2c914445/metrics-catalog/services/lib/sidekiq-helpers.libsonnet#L25-38) + **10 seconds** for high-urgency jobs and **5 minutes** for other + jobs. + + Some stage groups may have more services than these, and the + thresholds for those will be in the metrics catalog as well. + 1. Error rate: The rate of operations that had errors. The calculation to a ratio then happens as follows: @@ -143,14 +163,7 @@ stageGroupDashboards.dashboard('product_planning') .stageGroupDashboardTrailer() ``` -We provide basic customization to filter out the components essential to your group's activities. By default, all components `web`, `api`, `git`, and `sidekiq` are available in the dashboard. We can change this to only show `web` and `api`, or only show `sidekiq`: - -```jsonnet -stageGroupDashboards.dashboard('product_planning', components=['web', 'api']).stageGroupDashboardTrailer() -# Or -stageGroupDashboards.dashboard('product_planning', components=['sidekiq']).stageGroupDashboardTrailer() - -``` +We provide basic customization to filter out the components essential to your group's activities. By default, only the `web`, `api`, and `sidekiq` components are available in the dashboard, while `git` is hidden. See [how to enable available components and optional graphs](#optional-graphs). You can also append further information or custom metrics to a dashboard. This is an example that adds some links and a total request rate on the top of the page: @@ -166,7 +179,7 @@ stageGroupDashboards.dashboard('source_code') mode='markdown', content=||| Useful link for the Source Code Management group dashboard: - - [Issue list](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name%5B%5D=repository) + - [Issue list](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&state=opened&label_name%5B%5D=repository) - [Epic list](https://gitlab.com/groups/gitlab-org/-/epics?label_name[]=repository) |||, ), @@ -199,3 +212,31 @@ If you want to see the workflow in action, we've recorded a pairing session on c available on [GitLab Unfiltered](https://youtu.be/shEd_eiUjdI). For deeper customization and more complicated metrics, visit the [Grafonnet lib](https://github.com/grafana/grafonnet-lib) project and the [GitLab Prometheus Metrics](../administration/monitoring/prometheus/gitlab_metrics.md#gitlab-prometheus-metrics) documentation. + +### Optional Graphs + +Some Graphs aren't relevant for all groups, so they aren't added to +the dashboard by default. They can be added by customizing the +dashboard. + +By default, only the `web`, `api`, and `sidekiq` metrics are +shown. If you wish to see the metrics from the `git` fleet (or any +other component that might be added in the future), this could be +configured as follows: + +```jsonnet +stageGroupDashboards +.dashboard('source_code', components=stageGroupDashboards.supportedComponents) +.stageGroupDashboardTrailer() +``` + +If your group is interested in Sidekiq job durations and their +thresholds, these graphs can be added by calling the +`.addSidekiqJobDurationByUrgency` function: + +```jsonnet +stageGroupDashboards +.dashboard('access') +.addSidekiqJobDurationByUrgency() +.stageGroupDashboardTrailer() +``` diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index c3125f52cf2..c44e26927fe 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -851,6 +851,47 @@ using expectations, or dependency injection along with stubs, to avoid the need for modifications. If you have no other choice, an `around` block like the global variables example can be used, but avoid this if at all possible. +#### Elasticsearch specs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61171) in GitLab 14.0. + +Specs that require Elasticsearch must be marked with the `:elastic` trait. This +creates and deletes indices between examples to ensure a clean index, so that there is no room +for polluting the tests with nonessential data. +Most tests for Elasticsearch logic relate to: + +- Creating data in Postgres and waiting for it to be indexed in Elasticsearch. +- Searching for that data. +- Ensuring that the test gives the expected result. + +There are some exceptions, such as checking for structural changes rather than individual records in an index. + +The `:elastic_with_delete_by_query` trait was added to reduce run time for pipelines by creating and deleting indices +at the start and end of each context only. The [Elasticsearch DeleteByQuery API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html) +is used to delete data in all indices in between examples to ensure a clean index. + +Note that Elasticsearch indexing uses [`Gitlab::Redis::SharedState`](../../../ee/development/redis.md#gitlabrediscachesharedstatequeues). +Therefore, the Elasticsearch traits dynamically use the `:clean_gitlab_redis_shared_state` trait. +You do NOT need to add `:clean_gitlab_redis_shared_state` manually. + +Specs using Elasticsearch require that you: + +- Create data in Postgres and then index it into Elasticsearch. +- Enable Application Settings for Elasticsearch (which is disabled by default). + +To do so, use: + +```ruby +before do + stub_ee_application_setting(elasticsearch_search: true, elasticsearch_indexing: true) +end +``` + +Additionally, you can use the `ensure_elasticsearch_index!` method to overcome the asynchronous nature of Elasticsearch. +It uses the [Elasticsearch Refresh API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-refresh.html#refresh-api-desc) +to make sure all operations performed on an index since the last refresh are available for search. This method is typically +called after loading data into Postgres to ensure the data is indexed and searchable. + #### Test Snowplow events WARNING: @@ -954,6 +995,7 @@ Only use simple values as input in the `where` block. Using objects, FactoryBot-created objects, and similar items can lead to [unexpected results](https://github.com/tomykaira/rspec-parameterized/issues/8). <!-- vale gitlab.Spelling = YES --> + ### Prometheus tests Prometheus metrics may be preserved from one test run to another. To ensure that metrics are @@ -1034,6 +1076,16 @@ expect(json_string).to be_valid_json expect(json_string).to be_valid_json.and match_schema(schema) ``` +#### `be_one_of(collection)` + +The inverse of `include`, tests that the `collection` includes the expected +value: + +```ruby +expect(:a).to be_one_of(%i[a b c]) +expect(:z).not_to be_one_of(%i[a b c]) +``` + ### Testing query performance Testing query performance allows us to: @@ -1097,7 +1149,7 @@ module Spec module Helpers module CycleAnalyticsHelpers def create_commit_referencing_issue(issue, branch_name: random_git_name) - project.repository.add_branch(user, branch_name, 'master') + project.repository.add_branch(user, branch_name, 'main') create_commit("Commit for ##{issue.iid}", issue.project, user, branch_name) end end @@ -1154,7 +1206,7 @@ let(:project) { create(:project, :repository) } ``` Where you can, consider using the `:custom_repo` trait instead of `:repository`. -This allows you to specify exactly what files appear in the `master` branch +This allows you to specify exactly what files appear in the `main` branch of the project's repository. For example: ```ruby diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md index 7318f767219..e3fccdcee34 100644 --- a/doc/development/testing_guide/ci.md +++ b/doc/development/testing_guide/ci.md @@ -12,7 +12,7 @@ Our current CI parallelization setup is as follows: 1. The `retrieve-tests-metadata` job in the `prepare` stage ensures we have a `knapsack/report-master.json` file: - - The `knapsack/report-master.json` file is fetched from the latest `master` pipeline which runs `update-tests-metadata` + - The `knapsack/report-master.json` file is fetched from the latest `main` pipeline which runs `update-tests-metadata` (for now it's the 2-hourly scheduled master pipeline), if it's not here we initialize the file with `{}`. 1. Each `[rspec|rspec-ee] [unit|integration|system|geo] n m` job are run with `knapsack rspec` and should have an evenly distributed share of tests: @@ -31,7 +31,7 @@ After that, the next pipeline uses the up-to-date `knapsack/report-master.json` ## Monitoring -The GitLab test suite is [monitored](../performance.md#rspec-profiling) for the `master` branch, and any branch +The GitLab test suite is [monitored](../performance.md#rspec-profiling) for the `main` branch, and any branch that includes `rspec-profile` in their name. ## CI setup diff --git a/doc/development/testing_guide/end_to_end/beginners_guide.md b/doc/development/testing_guide/end_to_end/beginners_guide.md index 7cde2cad300..e0f0e9e7089 100644 --- a/doc/development/testing_guide/end_to_end/beginners_guide.md +++ b/doc/development/testing_guide/end_to_end/beginners_guide.md @@ -41,11 +41,11 @@ Does sufficient test coverage exist at the unit, feature, or integration levels? If you answered *yes*, then you *don't* need an end-to-end test. For information about the distribution of tests per level in GitLab, see -[Testing Levels](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/development/testing_guide/testing_levels.md). +[Testing Levels](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/testing_guide/testing_levels.md). - See the - [How to test at the correct level?](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/development/testing_guide/testing_levels.md#how-to-test-at-the-correct-level) - section of the [Testing levels](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/development/testing_guide/testing_levels.md) document. + [How to test at the correct level?](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/testing_guide/testing_levels.md#how-to-test-at-the-correct-level) + section of the [Testing levels](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/testing_guide/testing_levels.md) document. - Review how often the feature changes. Stable features that don't change very often might not be worth covering with end-to-end tests if they are already covered in lower level tests. 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 e3719393d41..c9acb2e9371 100644 --- a/doc/development/testing_guide/end_to_end/feature_flags.md +++ b/doc/development/testing_guide/end_to_end/feature_flags.md @@ -72,7 +72,7 @@ Runtime::Feature.enable(:feature_flag_name) It's also possible to run an entire scenario with a feature flag enabled, without having to edit existing tests or write new ones. -Please see the [QA README](https://gitlab.com/gitlab-org/gitlab/tree/master/qa#running-tests-with-a-feature-flag-enabled) +Please see the [QA README](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa#running-tests-with-a-feature-flag-enabled) for details. ## Confirming that end-to-end tests pass with a feature flag enabled @@ -81,7 +81,7 @@ End-to-end tests should pass with a feature flag enabled before it is enabled on If a test enables a feature flag as describe above, it is sufficient to run the `package-and-qa` job in a merge request containing the relevant changes. Or, if the feature flag and relevant changes have already been merged, you can confirm that the tests -pass on `master`. The end-to-end tests run on `master` every two hours, and the results are posted to a [Test +pass on `main`. The end-to-end tests run on `main` every two hours, and the results are posted to a [Test Session Report, which is available in the testcase-sessions project](https://gitlab.com/gitlab-org/quality/testcase-sessions/-/issues?label_name%5B%5D=found%3Amaster). If the relevant tests do not enable the feature flag themselves, you can check if the tests will need diff --git a/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png b/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png Binary files differindex 9ceccd39025..d5a2522ed82 100644 --- a/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png +++ b/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png diff --git a/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png b/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png Binary files differindex 489a043f52e..55eecaf8adf 100644 --- a/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png +++ b/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index e6da4771e55..6ab288b0525 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -100,7 +100,8 @@ You may have noticed that we use `gitlab-org/build/omnibus-gitlab-mirror` instea This is due to technical limitations in the GitLab permission model: the ability to run a pipeline against a protected branch is controlled by the ability to push/merge to this branch. This means that for developers to be able to trigger a pipeline for the default branch in -`gitlab-org/omnibus-gitlab`/`gitlab-org/gitlab-qa`, they would need to have Maintainer permission in those projects. +`gitlab-org/omnibus-gitlab`/`gitlab-org/gitlab-qa`, they would need to have the +[Maintainer role](../../../user/permissions.md) for those projects. For security reasons and implications, we couldn't open up the default branch to all the Developers. Hence we created these mirrors where Developers and Maintainers are allowed to push/merge to the default branch. This problem was discovered in <https://gitlab.com/gitlab-org/gitlab-qa/-/issues/63#note_107175160> and the "mirror" @@ -179,7 +180,7 @@ of the test scenarios you can run via the orchestrator](https://gitlab.com/gitla On the other hand, if you would like to run against a local development GitLab environment, you can use the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/). -Please refer to the instructions in the [QA README](https://gitlab.com/gitlab-org/gitlab/tree/master/qa/README.md#how-can-i-use-it) +Please refer to the instructions in the [QA README](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/README.md#how-can-i-use-it) and the section below. ### Running tests that require special setup @@ -192,7 +193,7 @@ In order to write new tests, you first need to learn more about GitLab QA architecture. See the [documentation about it](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/architecture.md). Once you decided where to put [test environment orchestration scenarios](https://gitlab.com/gitlab-org/gitlab-qa/tree/master/lib/gitlab/qa/scenario) and -[instance-level scenarios](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/qa/qa/specs/features), take a look at the [GitLab QA README](https://gitlab.com/gitlab-org/gitlab/tree/master/qa/README.md), +[instance-level scenarios](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/qa/qa/specs/features), take a look at the [GitLab QA README](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/README.md), the [GitLab QA orchestrator README](https://gitlab.com/gitlab-org/gitlab-qa/tree/master/README.md), and [the already existing instance-level scenarios](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/qa/qa/specs/features). diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md index 549ab95a5d1..859b8f950e3 100644 --- a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md +++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Jenkins spec -The [`jenkins_build_status_spec`](https://gitlab.com/gitlab-org/gitlab/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb) spins up a Jenkins instance in a Docker container based on an image stored in the [GitLab-QA container registry](https://gitlab.com/gitlab-org/gitlab-qa/container_registry). +The [`jenkins_build_status_spec`](https://gitlab.com/gitlab-org/gitlab/-/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb) spins up a Jenkins instance in a Docker container based on an image stored in the [GitLab-QA container registry](https://gitlab.com/gitlab-org/gitlab-qa/container_registry). The Docker image it uses is preconfigured with some base data and plugins. The test then configures the GitLab plugin in Jenkins with a URL of the GitLab instance that are used to run the tests. Unfortunately, the GitLab Jenkins plugin does not accept ports so `http://localhost:3000` would @@ -47,7 +47,7 @@ Jenkins is available on `http://localhost:8080`. Admin username is `admin` and password is `password`. -It is worth noting that this is not an orchestrated test. It is [tagged with the `:orchestrated` meta](https://gitlab.com/gitlab-org/gitlab/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb#L5) +It is worth noting that this is not an orchestrated test. It is [tagged with the `:orchestrated` meta](https://gitlab.com/gitlab-org/gitlab/-/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb#L5) only to prevent it from running in the pipelines for live environments such as Staging. ### Troubleshooting diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index 6b1c7a7eb58..bfcd68dbaf3 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -13,7 +13,7 @@ eventually. ## Quarantined tests -When a test frequently fails in `master`, +When a test frequently fails in `main`, [a ~"master:broken" issue](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) should be created. If the test cannot be fixed in a timely fashion, there is an impact on the @@ -53,10 +53,10 @@ Quarantined tests are run on the CI in dedicated jobs that are allowed to fail: ## Automatic retries and flaky tests detection On our CI, we use [RSpec::Retry](https://github.com/NoRedInk/rspec-retry) to automatically retry a failing example a few -times (see [`spec/spec_helper.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/spec_helper.rb) for the precise retries count). +times (see [`spec/spec_helper.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/spec_helper.rb) for the precise retries count). We also use a home-made `RspecFlaky::Listener` listener which records flaky -examples in a JSON report file on `master` (`retrieve-tests-metadata` and +examples in a JSON report file on `main` (`retrieve-tests-metadata` and `update-tests-metadata` jobs). This was originally implemented in: <https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13021>. diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 911fbd43989..8573fa81718 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -54,7 +54,7 @@ which have to be stubbed. - Jest runs in a Node.js environment, not in a browser. Support for running Jest tests in a browser [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/26982). - Because Jest runs in a Node.js environment, it uses [jsdom](https://github.com/jsdom/jsdom) by default. See also its [limitations](#limitations-of-jsdom) below. - Jest does not have access to Webpack loaders or aliases. - The aliases used by Jest are defined in its [own configuration](https://gitlab.com/gitlab-org/gitlab/blob/master/jest.config.js). + The aliases used by Jest are defined in its [own configuration](https://gitlab.com/gitlab-org/gitlab/-/blob/master/jest.config.js). - All calls to `setTimeout` and `setInterval` are mocked away. See also [Jest Timer Mocks](https://jestjs.io/docs/timer-mocks). - `rewire` is not required because Jest supports mocking modules. See also [Manual Mocks](https://jestjs.io/docs/manual-mocks). - No [context object](https://jasmine.github.io/tutorials/your_first_suite#section-The_%3Ccode%3Ethis%3C/code%3E_keyword) is passed to tests in Jest. @@ -83,13 +83,13 @@ Running `yarn jest-debug` runs Jest in debug mode, allowing you to debug/inspect ### Timeout error The default timeout for Jest is set in -[`/spec/frontend/test_setup.js`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/frontend/test_setup.js). +[`/spec/frontend/test_setup.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/frontend/test_setup.js). If your test exceeds that time, it fails. If you cannot improve the performance of the tests, you can increase the timeout for a specific test using -[`setTestTimeout`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/frontend/__helpers__/timeout.js). +[`setTestTimeout`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/frontend/__helpers__/timeout.js). ```javascript import { setTestTimeout } from 'helpers/timeout'; @@ -249,7 +249,7 @@ it('exists', () => { wrapper.findByText(/Click Me/i) // Good (especially for unit tests) - wrapper.find(FooComponent); + wrapper.findComponent(FooComponent); wrapper.find('input[name=foo]'); wrapper.find('[data-testid="my-foo-id"]'); wrapper.findByTestId('my-foo-id'); // with shallowMountExtended or mountExtended – check below @@ -281,7 +281,7 @@ Example: ```javascript it('exists', () => { - wrapper.find(FooComponent); + wrapper.findComponent(FooComponent); }); ``` @@ -386,7 +386,7 @@ Sometimes we have to test time-sensitive code. For example, recurring events tha #### `setTimeout()` / `setInterval()` in application If the application itself is waiting for some time, mock await the waiting. In Jest this is already -[done by default](https://gitlab.com/gitlab-org/gitlab/blob/a2128edfee799e49a8732bfa235e2c5e14949c68/jest.config.js#L47) +[done by default](https://gitlab.com/gitlab-org/gitlab/-/blob/a2128edfee799e49a8732bfa235e2c5e14949c68/jest.config.js#L47) (see also [Jest Timer Mocks](https://jestjs.io/docs/timer-mocks)). In Karma you can use the [Jasmine mock clock](https://jasmine.github.io/api/2.9/Clock.html). @@ -748,7 +748,7 @@ Jest supports [manual module mocks](https://jestjs.io/docs/manual-mocks) by plac (e.g. `app/assets/javascripts/ide/__mocks__`). **Don't do this.** We want to keep all of our test-related code in one place (the `spec/` folder). If a manual mock is needed for a `node_modules` package, use the `spec/frontend/__mocks__` folder. Here's an example of -a [Jest mock for the package `monaco-editor`](https://gitlab.com/gitlab-org/gitlab/blob/b7f914cddec9fc5971238cdf12766e79fa1629d7/spec/frontend/__mocks__/monaco-editor/index.js#L1). +a [Jest mock for the package `monaco-editor`](https://gitlab.com/gitlab-org/gitlab/-/blob/b7f914cddec9fc5971238cdf12766e79fa1629d7/spec/frontend/__mocks__/monaco-editor/index.js#L1). If a manual mock is needed for a CE module, place it in `spec/frontend/mocks/ce`. @@ -759,12 +759,12 @@ If a manual mock is needed for a CE module, place it in `spec/frontend/mocks/ce` #### Manual mock examples -- [`mocks/axios_utils`](https://gitlab.com/gitlab-org/gitlab/blob/bd20aeb64c4eed117831556c54b40ff4aee9bfd1/spec/frontend/mocks/ce/lib/utils/axios_utils.js#L1) - +- [`mocks/axios_utils`](https://gitlab.com/gitlab-org/gitlab/-/blob/bd20aeb64c4eed117831556c54b40ff4aee9bfd1/spec/frontend/mocks/ce/lib/utils/axios_utils.js#L1) - This mock is helpful because we don't want any unmocked requests to pass any tests. Also, we are able to inject some test helpers such as `axios.waitForAll`. -- [`__mocks__/mousetrap/index.js`](https://gitlab.com/gitlab-org/gitlab/blob/cd4c086d894226445be9d18294a060ba46572435/spec/frontend/__mocks__/mousetrap/index.js#L1) - +- [`__mocks__/mousetrap/index.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/cd4c086d894226445be9d18294a060ba46572435/spec/frontend/__mocks__/mousetrap/index.js#L1) - This mock is helpful because the module itself uses AMD format which webpack understands, but is incompatible with the jest environment. This mock doesn't remove any behavior, only provides a nice es6 compatible wrapper. -- [`__mocks__/monaco-editor/index.js`](https://gitlab.com/gitlab-org/gitlab/blob/b7f914cddec9fc5971238cdf12766e79fa1629d7/spec/frontend/__mocks__/monaco-editor/index.js) - +- [`__mocks__/monaco-editor/index.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/b7f914cddec9fc5971238cdf12766e79fa1629d7/spec/frontend/__mocks__/monaco-editor/index.js) - This mock is helpful because the Monaco package is completely incompatible in a Jest environment. In fact, webpack requires a special loader to make it work. This mock makes this package consumable by Jest. @@ -1109,7 +1109,7 @@ See also [Notes on testing Vue components](../fe_guide/vue.md#testing-vue-compon ## Test helpers -Test helpers can be found in [`spec/frontend/__helpers__`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/frontend/__helpers__). +Test helpers can be found in [`spec/frontend/__helpers__`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/frontend/__helpers__). If you introduce new helpers, place them in that directory. ### Vuex Helper: `testAction` diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index c4194be23a4..cf757aad870 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -81,6 +81,8 @@ subgraph "CNG-mirror pipeline" - Since we're using [the official GitLab Helm chart](https://gitlab.com/gitlab-org/charts/gitlab/), this means you get a dedicated environment for your branch that's very close to what it would look in production. + - Each review app is deployed to its own Kubernetes namespace. The namespace is based on the Review App slug that is + unique to each branch. 1. Once the [`review-deploy`](https://gitlab.com/gitlab-org/gitlab/-/jobs/467724810) job succeeds, you should be able to use your Review App thanks to the direct link to it from the MR widget. To log into the Review App, see "Log into my Review App?" below. @@ -132,6 +134,9 @@ the QA smoke suite. You can also manually start the `review-qa-all`: it runs the full QA suite. +After the end-to-end test runs have finished, [Allure reports](https://github.com/allure-framework/allure2) are generated and published by +the `allure-report-qa-smoke` and `allure-report-qa-all` jobs. A comment with links to the reports are added to the merge request. + ## Performance Metrics On every [pipeline](https://gitlab.com/gitlab-org/gitlab/pipelines/125315730) in the `qa` stage, the @@ -141,12 +146,7 @@ browser performance testing using a ## Cluster configuration -### Node pools - -The `review-apps` cluster is currently set up with -the following node pools: - -- `e2-highcpu-16` (16 vCPU, 16 GB memory) pre-emptible nodes with autoscaling +The cluster is configured via Terraform in the [`engineering-productivity-infrastructure`](https://gitlab.com/gitlab-org/quality/engineering-productivity-infrastructure) project. Node pool image type must be `Container-Optimized OS (cos)`, not `Container-Optimized OS with Containerd (cos_containerd)`, due to this [known issue on GitLab Runner Kubernetes executor](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4755) @@ -200,7 +200,7 @@ the GitLab handbook information for the [shared 1Password account](https://about 1. Click on the `KUBECTL` dropdown, then `Exec` -> `task-runner`. 1. Replace `-c task-runner -- ls` with `-it -- gitlab-rails console` from the default command or - - Run `kubectl exec --namespace review-apps review-qa-raise-e-12chm0-task-runner-d5455cc8-2lsvz -it -- gitlab-rails console` and + - Run `kubectl exec --namespace review-qa-raise-e-12chm0 review-qa-raise-e-12chm0-task-runner-d5455cc8-2lsvz -it -- gitlab-rails console` and - Replace `review-qa-raise-e-12chm0-task-runner-d5455cc8-2lsvz` with your Pod's name. @@ -218,7 +218,7 @@ the GitLab handbook information for the [shared 1Password account](https://about ## Diagnosing unhealthy Review App releases If [Review App Stability](https://app.periscopedata.com/app/gitlab/496118/Engineering-Productivity-Sandbox?widget=6690556&udv=785399) -dips this may be a signal that the `review-apps-ce/ee` cluster is unhealthy. +dips this may be a signal that the `review-apps` cluster is unhealthy. Leading indicators may be health check failures leading to restarts or majority failure for Review App deployments. The [Review Apps Overview dashboard](https://console.cloud.google.com/monitoring/classic/dashboards/6798952013815386466?project=gitlab-review-apps&timeDomain=1d) diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index abacb9a0c87..3a4a28702c7 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -48,7 +48,7 @@ records should use stubs/doubles as much as possible. | `config/` | `spec/config/` | RSpec | | | `config/initializers/` | `spec/initializers/` | RSpec | | | `config/routes.rb`, `config/routes/` | `spec/routing/` | RSpec | | -| `config/puma.example.development.rb`, `config/unicorn.rb.example` | `spec/rack_servers/` | RSpec | | +| `config/puma.example.development.rb` | `spec/rack_servers/` | RSpec | | | `db/` | `spec/db/` | RSpec | | | `db/{post_,}migrate/` | `spec/migrations/` | RSpec | More details in the [Testing Rails migrations guide](testing_migrations_guide.md). | | `Gemfile` | `spec/dependencies/`, `spec/sidekiq/` | RSpec | | @@ -486,7 +486,7 @@ Note that: - data needed for the tests can only be created using the GUI or the API - expectations can only be made against the browser page and API responses -Every new feature should come with a [test plan](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab/issue_templates/Test%20plan.md). +Every new feature should come with a [test plan](https://gitlab.com/gitlab-org/gitlab/-/tree/master/.gitlab/issue_templates/Test%20plan.md). | Tests path | Testing engine | Notes | | ---------- | -------------- | ----- | diff --git a/doc/development/testing_guide/testing_rake_tasks.md b/doc/development/testing_guide/testing_rake_tasks.md index dc754721e24..30d193de2f2 100644 --- a/doc/development/testing_guide/testing_rake_tasks.md +++ b/doc/development/testing_guide/testing_rake_tasks.md @@ -11,19 +11,21 @@ in lieu of the standard Spec helper. Instead of `require 'spec_helper'`, use `require 'rake_helper'`. The helper includes `spec_helper` for you, and configures a few other things to make testing Rake tasks easier. -At a minimum, requiring the Rake helper redirects `stdout`, include the -runtime task helpers, and include the `RakeHelpers` Spec support module. +At a minimum, requiring the Rake helper includes the runtime task helpers, and +includes the `RakeHelpers` Spec support module. The `RakeHelpers` module exposes a `run_rake_task(<task>)` method to make executing tasks simple. See `spec/support/helpers/rake_helpers.rb` for all available methods. +`$stdout` can be redirected by adding `:silence_stdout`. + Example: ```ruby require 'rake_helper' -describe 'gitlab:shell rake tasks' do +describe 'gitlab:shell rake tasks', :silence_stdout do before do Rake.application.rake_require 'tasks/gitlab/shell' diff --git a/doc/development/understanding_explain_plans.md b/doc/development/understanding_explain_plans.md index e0176c190d6..66dc1fef31a 100644 --- a/doc/development/understanding_explain_plans.md +++ b/doc/development/understanding_explain_plans.md @@ -704,7 +704,7 @@ Execution time: 0.113 ms ### ChatOps -[GitLab employees can also use our ChatOps solution, available in Slack using the +[GitLab team members can also use our ChatOps solution, available in Slack using the `/chatops` slash command](chatops_on_gitlabcom.md). You can use ChatOps to get a query plan by running the following: @@ -728,7 +728,7 @@ For more information about the available options, run: ### `#database-lab` -Another tool GitLab employees can use is a chatbot powered by [Joe](https://gitlab.com/postgres-ai/joe) +Another tool GitLab team members can use is a chatbot powered by [Joe](https://gitlab.com/postgres-ai/joe) which uses [Database Lab](https://gitlab.com/postgres-ai/database-lab) to instantly provide developers with their own clone of the production database. diff --git a/doc/development/uploads.md b/doc/development/uploads.md index 7ffa9014240..7cdc3875fd6 100644 --- a/doc/development/uploads.md +++ b/doc/development/uploads.md @@ -216,8 +216,8 @@ Workhorse asks rails for temporary pre-signed object storage URLs and directly u In this setup, an extra Rails route must be implemented in order to handle authorization. Examples of this can be found in: -- [`Projects::LfsStorageController`](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/app/controllers/projects/lfs_storage_controller.rb) - and [its routes](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/config/routes/git_http.rb#L31-32). +- [`Projects::LfsStorageController`](https://gitlab.com/gitlab-org/gitlab/-/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/app/controllers/projects/lfs_storage_controller.rb) + and [its routes](https://gitlab.com/gitlab-org/gitlab/-/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/config/routes/git_http.rb#L31-32). - [API endpoints for uploading packages](packages.md#file-uploads). This falls back to _disk buffered upload_ when `direct_upload` is disabled inside the [object storage setting](../administration/uploads.md#object-storage-settings). @@ -323,7 +323,7 @@ For a Grape API upload, we can have [body or a multipart](#upload-encodings) upl Workhorse pre-upload authorization and one for accepting the upload metadata from Workhorse: 1. Implement an endpoint with the URL + `/authorize` suffix that will: - - Check that the request is coming from Workhorse with the `require_gitlab_workhorse!` from the [API helpers](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/helpers.rb). + - Check that the request is coming from Workhorse with the `require_gitlab_workhorse!` from the [API helpers](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/helpers.rb). - Check user permissions. - Set the status to `200` with `status 200`. - Set the content type with `content_type Gitlab::Workhorse::INTERNAL_API_CONTENT_TYPE`. @@ -334,7 +334,7 @@ Workhorse pre-upload authorization and one for accepting the upload metadata fro use `requires :file, type: ::API::Validations::Types::WorkhorseFile`. - Body upload requests have their upload available under the parameter `file`. - Check that the request is coming from Workhorse with the `require_gitlab_workhorse!` from the -[API helpers](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/helpers.rb). +[API helpers](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/helpers.rb). - Check the user permissions. - The remaining code of the processing. This is where the code must be reading the parameter (for our example, it would be `params[:file]`). diff --git a/doc/development/usage_ping.md b/doc/development/usage_ping.md index b8f08caaebd..567a2d41c33 100644 --- a/doc/development/usage_ping.md +++ b/doc/development/usage_ping.md @@ -1,7 +1,9 @@ --- redirect_to: 'usage_ping/index.md' +remove_date: '2021-05-23' --- This document was moved to [another location](usage_ping/index.md). + <!-- This redirect file can be deleted after <2021-05-23>. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/development/usage_ping/dictionary.md b/doc/development/usage_ping/dictionary.md index 75d65f8e5df..e76fb302b9c 100644 --- a/doc/development/usage_ping/dictionary.md +++ b/doc/development/usage_ping/dictionary.md @@ -36,7 +36,7 @@ was released. ### `active_user_count` -This is named the instance_user_count in the Versions application. +The number of active users existing in the instance. This is named the instance_user_count in the Versions application. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/20210204124829_active_user_count.yml) @@ -162,7 +162,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: @@ -282,7 +282,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -372,15 +372,15 @@ Tiers: `free` ### `container_registry_enabled` -Whether container registry is enabled +A count of projects where the container registry is enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210204124858_container_registry_enabled.yml) -Group: `group::product intelligence` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `container_registry_server.vendor` @@ -392,7 +392,7 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `container_registry_server.version` @@ -404,7 +404,7 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.alert_bot_incident_issues` @@ -508,7 +508,7 @@ Unique builds in project [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175510_ci_builds.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -520,7 +520,7 @@ Total pipelines in external repositories [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175514_ci_external_pipelines.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -532,7 +532,7 @@ Total pipelines in GitLab repositories [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175512_ci_internal_pipelines.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -556,7 +556,7 @@ Total Pipelines from templates in repository [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175518_ci_pipeline_config_repository.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -568,7 +568,7 @@ Pipeline schedules in GitLab [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175523_ci_pipeline_schedules.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -580,7 +580,7 @@ Total configured Runners in project [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175520_ci_runners.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -592,9 +592,9 @@ Total active instance Runners [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502050341_ci_runners_group_type_active.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -604,9 +604,9 @@ Total active and online group Runners [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502051922_ci_runners_group_type_active_online.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -616,9 +616,9 @@ Total active group Runners [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502045402_ci_runners_instance_type_active.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -628,9 +628,9 @@ Total active and online instance Runners [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502051651_ci_runners_instance_type_active_online.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -640,9 +640,9 @@ Total online Runners [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502050942_ci_runners_online.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -652,9 +652,9 @@ Total active project Runners [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502050834_ci_runners_project_type_active.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -664,9 +664,9 @@ Total active and online project Runners [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502052036_ci_runners_project_type_active_online.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -676,7 +676,7 @@ Total configured Triggers in project [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175521_ci_triggers.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -936,7 +936,7 @@ Tiers: `free` ### `counts.cycle_analytics_views` -Missing description +Total visits to VSA (both group- and project-level) all time [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174832_cycle_analytics_views.yml) @@ -944,7 +944,7 @@ Group: `group::optimize` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.dast_jobs` @@ -1020,39 +1020,39 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.design_management_designs_create` -Missing description +Number of designs that were created [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180740_design_management_designs_create.yml) -Group: `group::knowledge` +Group: `group::product planning` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.design_management_designs_delete` -Missing description +Number of designs that were deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180743_design_management_designs_delete.yml) -Group: `group::knowledge` +Group: `group::product planning` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.design_management_designs_update` -Missing description +Number of updates to designs [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180741_design_management_designs_update.yml) -Group: `group::knowledge` +Group: `group::product planning` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.environments` @@ -1126,54 +1126,6 @@ Status: `data_available` Tiers: `free` -### `counts.g_project_management_users_checking_epic_task_monthly` - -Counts of MAU checking epic task - -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210421080207_g_project_management_users_checking_epic_task_monthly.yml) - -Group: `group::product planning` - -Status: `implemented` - -Tiers: `premium`, `ultimate` - -### `counts.g_project_management_users_checking_epic_task_weekly` - -Counts of WAU checking epic task - -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210421075943_g_project_management_users_checking_epic_task_weekly.yml) - -Group: `group::product planning` - -Status: `implemented` - -Tiers: `premium`, `ultimate` - -### `counts.g_project_management_users_unchecking_epic_task_monthly` - -Counts of MAU unchecking epic task - -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210421102516_g_project_management_users_unchecking_epic_task_monthly.yml) - -Group: `group::product planning` - -Status: `implemented` - -Tiers: `premium`, `ultimate` - -### `counts.g_project_management_users_unchecking_epic_task_weekly` - -Counts of WAU unchecking epic task - -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210421102812_g_project_management_users_unchecking_epic_task_weekly.yml) - -Group: `group::product planning` - -Status: `implemented` - -Tiers: `premium`, `ultimate` - ### `counts.geo_event_log_max_id` Number of replication events on a Geo primary @@ -1240,7 +1192,7 @@ Total count of groups as of usage ping snapshot [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180750_groups.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` @@ -1344,15 +1296,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.groups_datadog_active` -Missing description +Count of groups with active integrations for Datadog [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182549_groups_datadog_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.groups_discord_active` @@ -1392,15 +1344,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.groups_ewm_active` -Missing description +Count of groups with active integrations for EWM [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182616_groups_ewm_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.groups_external_wiki_active` @@ -1430,13 +1382,13 @@ Tiers: `free`, `premium`, `ultimate` Count of groups with active integrations for GitHub -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175850_groups_github_active.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175850_groups_github_active.yml) Group: `group::ecosystem` Status: `data_available` -Tiers: `free`, `premium`, `ultimate` +Tiers: `premium`, `ultimate` ### `counts.groups_hangouts_chat_active` @@ -1560,15 +1512,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.groups_inheriting_datadog_active` -Missing description +Count of active groups inheriting integrations for Datadog [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182557_groups_inheriting_datadog_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.groups_inheriting_discord_active` @@ -1608,15 +1560,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.groups_inheriting_ewm_active` -Missing description +Count of active groups inheriting integrations for EWM [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182623_groups_inheriting_ewm_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.groups_inheriting_external_wiki_active` @@ -1646,13 +1598,13 @@ Tiers: `free`, `premium`, `ultimate` Count of active groups inheriting integrations for GitHub -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175857_groups_inheriting_github_active.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175857_groups_inheriting_github_active.yml) Group: `group::ecosystem` Status: `data_available` -Tiers: `free`, `premium`, `ultimate` +Tiers: `premium`, `ultimate` ### `counts.groups_inheriting_hangouts_chat_active` @@ -1752,27 +1704,27 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.groups_inheriting_mock_ci_active` -Missing description +Count of active groups inheriting integrations for Mock CI [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182732_groups_inheriting_mock_ci_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.groups_inheriting_mock_monitoring_active` -Missing description +Count of active groups inheriting integrations for Mock Monitoring [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182743_groups_inheriting_mock_monitoring_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.groups_inheriting_packagist_active` @@ -1992,27 +1944,27 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.groups_mock_ci_active` -Missing description +Count of groups with active integrations for Mock CI [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182724_groups_mock_ci_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.groups_mock_monitoring_active` -Missing description +Count of groups with active integrations for Mock Monitoring [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182736_groups_mock_monitoring_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.groups_packagist_active` @@ -2166,7 +2118,7 @@ Total clicks on the create track's first email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2178,7 +2130,7 @@ Total sent emails of the create track's first email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2190,7 +2142,7 @@ Total clicks on the create track's second email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2202,7 +2154,7 @@ Total sent emails of the create track's second email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2214,7 +2166,7 @@ Total clicks on the create track's third email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2226,7 +2178,19 @@ Total sent emails of the create track's third email Group: `group::activation` -Status: `implemented` +Status: `data_available` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_experience_0_sent` + +Total sent emails of the experience track's first email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210518081225_in_product_marketing_email_experience_0_sent.yml) + +Group: `group::activation` + +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2238,7 +2202,7 @@ Total clicks on the team track's first email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2250,7 +2214,7 @@ Total sent emails of the team track's first email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2262,7 +2226,7 @@ Total clicks on the team track's second email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2274,7 +2238,7 @@ Total sent emails of the team track's second email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2286,7 +2250,7 @@ Total clicks on the team track's third email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2298,7 +2262,7 @@ Total sent emails of the team track's third email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2310,7 +2274,7 @@ Total clicks on the verify trial's first email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2322,7 +2286,7 @@ Total sent emails of the trial track's first email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2334,7 +2298,7 @@ Total clicks on the trial track's second email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2346,7 +2310,7 @@ Total sent emails of the trial track's second email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2358,7 +2322,7 @@ Total clicks on the trial track's third email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2370,7 +2334,7 @@ Total sent emails of the trial track's third email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2382,7 +2346,7 @@ Total clicks on the verify track's first email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2394,7 +2358,7 @@ Total sent emails of the verify track's first email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2406,7 +2370,7 @@ Total clicks on the verify track's second email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2418,7 +2382,7 @@ Total sent emails of the verify track's second email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2430,7 +2394,7 @@ Total clicks on the verify track's third email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2442,7 +2406,7 @@ Total sent emails of the verify track's third email Group: `group::activation` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -2490,7 +2454,7 @@ Whether or not ModSecurity is set to blocking mode Group: `group::container security` -Status: `deprecated` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -2502,7 +2466,7 @@ Whether or not ModSecurity is disabled within Ingress Group: `group::container security` -Status: `deprecated` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -2514,7 +2478,7 @@ Whether or not ModSecurity is set to logging mode Group: `group::container security` -Status: `deprecated` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -2526,7 +2490,7 @@ Whether or not ModSecurity has not been installed into the cluster Group: `group::container security` -Status: `deprecated` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -2538,7 +2502,7 @@ Cumulative count of packets identified as anomalous by ModSecurity since Usage P Group: `group::container security` -Status: `deprecated` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -2550,7 +2514,7 @@ Cumulative count of packets processed by ModSecurity since Usage Ping was last r Group: `group::container security` -Status: `deprecated` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -2562,7 +2526,7 @@ Whether or not ModSecurity statistics are unavailable Group: `group::container security` -Status: `deprecated` +Status: `removed` Tiers: `ultimate` @@ -2688,15 +2652,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.instances_datadog_active` -Missing description +Count of active instance-level integrations for Datadog [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182553_instances_datadog_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.instances_discord_active` @@ -2736,15 +2700,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.instances_ewm_active` -Missing description +Count of active instance-level integrations for EWM [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182620_instances_ewm_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.instances_external_wiki_active` @@ -2774,13 +2738,13 @@ Tiers: `free`, `premium`, `ultimate` Count of active instance-level integrations for GitHub -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175853_instances_github_active.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175853_instances_github_active.yml) Group: `group::ecosystem` Status: `data_available` -Tiers: `free`, `premium`, `ultimate` +Tiers: `premium`, `ultimate` ### `counts.instances_hangouts_chat_active` @@ -2880,27 +2844,27 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.instances_mock_ci_active` -Missing description +Count of active instance-level integrations for Mock CI [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182728_instances_mock_ci_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.instances_mock_monitoring_active` -Missing description +Count of active instance-level integrations for Mock Monitoring [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182739_instances_mock_monitoring_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.instances_packagist_active` @@ -3192,15 +3156,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.keys` -Missing description +Number of keys. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180752_keys.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.kubernetes_agent_gitops_sync` @@ -3222,7 +3186,7 @@ Count of Kubernetes API proxy requests Group: `group::configure` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -3302,13 +3266,13 @@ Tiers: `premium`, `ultimate` Number of users that are linked to LDAP -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174826_ldap_users.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174826_ldap_users.yml) Group: `group::access` Status: `data_available` -Tiers: `free`, `premium`, `ultimate` +Tiers: `premium`, `ultimate` ### `counts.lfs_objects` @@ -3316,7 +3280,7 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181009_lfs_objects.yml) -Group: `group::package` +Group: `group::create` Status: `data_available` @@ -3324,15 +3288,15 @@ Tiers: `free` ### `counts.license_management_jobs` -Name on the GitLab license +Count of License Scanning jobs run -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/20210204124854_license_management_jobs.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210204124854_license_management_jobs.yml) -Group: `group::product intelligence` +Group: `group::composition analysis` Status: `data_available` -Tiers: `premium`, `ultimate` +Tiers: `ultimate` ### `counts.licenses_list_views` @@ -3492,507 +3456,519 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_composer_delete_package` -Missing description +A count of Composer packages that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182855_package_events_i_package_composer_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_composer_pull_package` -Missing description +A count of Composer packages that have been downloaded [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182857_package_events_i_package_composer_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_composer_push_package` -Missing description +A count of Composer packages that have been published [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182859_package_events_i_package_composer_push_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_conan_delete_package` -Missing description +A count of Conan packages that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182901_package_events_i_package_conan_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_conan_pull_package` -Missing description +A count of Conan packages that have been downloaded [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182903_package_events_i_package_conan_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_conan_push_package` -Missing description +A count of Conan packages that have been published [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182905_package_events_i_package_conan_push_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_container_delete_package` -Missing description +A count of container images that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182907_package_events_i_package_container_delete_package.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_container_pull_package` -Missing description +A count of container images that have been downloaded [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182909_package_events_i_package_container_pull_package.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_container_push_package` -Missing description +A count of container images that have been published [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182911_package_events_i_package_container_push_package.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_debian_delete_package` -Missing description +A count of Debian packages that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182913_package_events_i_package_debian_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_debian_pull_package` -Missing description +A count of Debian packages that have been downloaded [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182915_package_events_i_package_debian_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_debian_push_package` -Missing description +A count of Debian packages that have been published [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182917_package_events_i_package_debian_push_package.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_delete_package` -Missing description +A count of packages that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182919_package_events_i_package_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_delete_package_by_deploy_token` -Missing description +A count of packages that have been deleted using a Deploy Token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182921_package_events_i_package_delete_package_by_deploy_token.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_delete_package_by_guest` -Missing description +A count of packages that have been deleted using a Guest [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182923_package_events_i_package_delete_package_by_guest.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_delete_package_by_user` -Missing description +A count of packages that have been deleted using a logged in user [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182925_package_events_i_package_delete_package_by_user.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_generic_delete_package` -Missing description +A count of generic packages that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182927_package_events_i_package_generic_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_generic_pull_package` -Missing description +A count of generic packages that have been downloaded [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182929_package_events_i_package_generic_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_generic_push_package` -Missing description +A count of generic packages that have been published [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182931_package_events_i_package_generic_push_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_golang_delete_package` -Missing description +A count of Go modules that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182933_package_events_i_package_golang_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_golang_pull_package` -Missing description +A count of Go modules that have been downloaded [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182934_package_events_i_package_golang_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_golang_push_package` -Missing description +A count of Go modules that have been published [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182936_package_events_i_package_golang_push_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` + +### `counts.package_events_i_package_helm_pull_package` + +Total count of pull Helm packages events + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210517073546_package_events_i_package_helm_pull_package.yml) + +Group: `group::package` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_maven_delete_package` -Missing description +A count of Maven packages that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182938_package_events_i_package_maven_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_maven_pull_package` -Missing description +A count of Maven packages that have been downloaded [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182940_package_events_i_package_maven_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_maven_push_package` -Missing description +A count of Maven packages that have been published [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182942_package_events_i_package_maven_push_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_npm_delete_package` -Missing description +A count of npm packages that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182944_package_events_i_package_npm_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_npm_pull_package` -Missing description +A count of npm packages that have been downloaded [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182946_package_events_i_package_npm_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_npm_push_package` -Missing description +A count of npm packages that have been published [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182948_package_events_i_package_npm_push_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_nuget_delete_package` -Missing description +A count of NuGet packages that have been deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182950_package_events_i_package_nuget_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_nuget_pull_package` -Missing description +A count of NuGet packages that have been downloaded [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182952_package_events_i_package_nuget_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_nuget_push_package` -Missing description +A count of NuGet packages that have been published [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182954_package_events_i_package_nuget_push_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_pull_package` -Missing description +A count of packages that have been downloaded from the package registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182956_package_events_i_package_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_pull_package_by_deploy_token` -Missing description +A count of packages that have been downloaded from the package registry using a Deploy Token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182958_package_events_i_package_pull_package_by_deploy_token.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_pull_package_by_guest` -Missing description +A count of packages that have been downloaded from the package registry by a guest [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183000_package_events_i_package_pull_package_by_guest.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_pull_package_by_user` -Missing description +A count of packages that have been downloaded from the package registry by a user [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183002_package_events_i_package_pull_package_by_user.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_push_package` -Missing description +A count of packages that have been published to the package registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183004_package_events_i_package_push_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_push_package_by_deploy_token` -Missing description +A count of packages that have been published to the package registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183005_package_events_i_package_push_package_by_deploy_token.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_push_package_by_guest` -Missing description +A count of packages that have been published to the package registry by a Guest [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183007_package_events_i_package_push_package_by_guest.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_push_package_by_user` -Missing description +A count of packages that have been published to the package registry by a user [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183009_package_events_i_package_push_package_by_user.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_pypi_delete_package` -Missing description +A count of Python packages that have been deleted from the package registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183011_package_events_i_package_pypi_delete_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_pypi_pull_package` -Missing description +A count of Python packages that have been downloaded from the package registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183013_package_events_i_package_pypi_pull_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_pypi_push_package` -Missing description +A count of Python packages that have been published to the package registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183015_package_events_i_package_pypi_push_package.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_rubygems_delete_package` @@ -4032,39 +4008,39 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_tag_delete_package` -Missing description +A count of package tags that have been deleted from the package registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183017_package_events_i_package_tag_delete_package.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_tag_pull_package` -Missing description +A count of package tags that have been downloaded from the package registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183019_package_events_i_package_tag_pull_package.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_tag_push_package` -Missing description +A count of package tags that have been published to the package registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183021_package_events_i_package_tag_push_package.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_terraform_module_delete_package` @@ -4074,7 +4050,7 @@ Total count of Terraform Module packages delete events Group: `group::configure` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -4086,7 +4062,7 @@ Total count of pull Terraform Module packages events Group: `group::configure` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -4098,13 +4074,13 @@ Total count of push Terraform Module packages events Group: `group::configure` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` ### `counts.packages` -Number of packages +The total number of packages published to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181012_packages.yml) @@ -4112,7 +4088,7 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.pages_domains` @@ -4128,7 +4104,7 @@ Tiers: `free` ### `counts.personal_snippets` -Count of Personal Snippets +Count of personal Snippets [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180239_personal_snippets.yml) @@ -4144,9 +4120,9 @@ Count the total number of log views [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175021_pod_logs_usages_total.yml) -Group: `group::apm` +Group: `group::monitor` -Status: `data_available` +Status: `removed` Tiers: `free` @@ -4164,7 +4140,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.productivity_analytics_views` -Missing description +Total visits to /groups/:group/-/analytics/productivity_analytics all time [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174834_productivity_analytics_views.yml) @@ -4172,7 +4148,7 @@ Group: `group::optimize` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.project_clusters_disabled` @@ -4200,7 +4176,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.project_snippets` -Count of Project Snippetss +Count of project Snippets [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180241_project_snippets.yml) @@ -4308,7 +4284,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.projects_creating_incidents` -Counts of Projects that have created incidents +Counts of Projects that have incident issues, regardless of status. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180453_projects_creating_incidents.yml) @@ -4332,15 +4308,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.projects_datadog_active` -Missing description +Count of projects with active integrations for Datadog [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182547_projects_datadog_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_discord_active` @@ -4380,15 +4356,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.projects_ewm_active` -Missing description +Count of projects with active integrations for EWM [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182614_projects_ewm_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_external_wiki_active` @@ -4418,13 +4394,13 @@ Tiers: `free`, `premium`, `ultimate` Count of projects with active integrations for GitHub -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175848_projects_github_active.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175848_projects_github_active.yml) Group: `group::ecosystem` Status: `data_available` -Tiers: `free`, `premium`, `ultimate` +Tiers: `premium`, `ultimate` ### `counts.projects_hangouts_chat_active` @@ -4560,15 +4536,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.projects_inheriting_datadog_active` -Missing description +Count of active projects inheriting integrations for Datadog [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182555_projects_inheriting_datadog_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_inheriting_discord_active` @@ -4608,15 +4584,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.projects_inheriting_ewm_active` -Missing description +Count of active projects inheriting integrations for EWM [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182622_projects_inheriting_ewm_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_inheriting_external_wiki_active` @@ -4646,13 +4622,13 @@ Tiers: `free`, `premium`, `ultimate` Count of active projects inheriting integrations for GitHub -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175855_projects_inheriting_github_active.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175855_projects_inheriting_github_active.yml) Group: `group::ecosystem` Status: `data_available` -Tiers: `free`, `premium`, `ultimate` +Tiers: `premium`, `ultimate` ### `counts.projects_inheriting_hangouts_chat_active` @@ -4752,27 +4728,27 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.projects_inheriting_mock_ci_active` -Missing description +Count of active projects inheriting integrations for Mock CI [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182730_projects_inheriting_mock_ci_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_inheriting_mock_monitoring_active` -Missing description +Count of active projects inheriting integrations for Mock Monitoring [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182741_projects_inheriting_mock_monitoring_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_inheriting_packagist_active` @@ -5056,7 +5032,7 @@ Projects with repository mirroring enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181920_projects_mirrored_with_pipelines_enabled.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -5064,27 +5040,27 @@ Tiers: `premium`, `ultimate` ### `counts.projects_mock_ci_active` -Missing description +Count of projects with active integrations for Mock CI [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182722_projects_mock_ci_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_mock_monitoring_active` -Missing description +Count of projects with active integrations for Mock Monitoring [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182734_projects_mock_monitoring_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_packagist_active` @@ -5280,7 +5256,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_disabled` -Missing description +The number of projects with cleanup policy for tags turned off [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181014_projects_with_expiration_policy_disabled.yml) @@ -5288,11 +5264,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled` -Missing description +A count of projects with the cleanup policy for tags turned on [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181016_projects_with_expiration_policy_enabled.yml) @@ -5300,11 +5276,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_cadence_set_to_14d` -Missing description +A count of projects with the cleanup policy set to run every 14 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181033_projects_with_expiration_policy_enabled_with_cadence_set_to_14d.yml) @@ -5312,11 +5288,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_cadence_set_to_1d` -Missing description +A count of projects with the cleanup policy set to run every day [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181029_projects_with_expiration_policy_enabled_with_cadence_set_to_1d.yml) @@ -5324,11 +5300,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_cadence_set_to_1month` -Missing description +A count of projects with the cleanup policy set to run monthly [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181035_projects_with_expiration_policy_enabled_with_cadence_set_to_1month.yml) @@ -5336,11 +5312,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_cadence_set_to_3month` -Missing description +A count of projects with the cleanup policy set to run every 3 months [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181037_projects_with_expiration_policy_enabled_with_cadence_set_to_3month.yml) @@ -5348,11 +5324,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_cadence_set_to_7d` -Missing description +A count of projects with the cleanup policy set to run every 7 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181031_projects_with_expiration_policy_enabled_with_cadence_set_to_7d.yml) @@ -5360,95 +5336,95 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_keep_n_set_to_1` -Missing description +A count of projects with the cleanup policy set to keep 1 tag -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181018_projects_with_expiration_policy_enabled_with_keep_n_set_to_1.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181018_projects_with_expiration_policy_enabled_with_keep_n_set_to_1.yml) Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_keep_n_set_to_10` -Missing description +A count of projects with the cleanup policy set to keep 10 tags -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181022_projects_with_expiration_policy_enabled_with_keep_n_set_to_10.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181022_projects_with_expiration_policy_enabled_with_keep_n_set_to_10.yml) Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_keep_n_set_to_100` -Missing description +A count of projects with the cleanup policy set to keep 100 tags -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181027_projects_with_expiration_policy_enabled_with_keep_n_set_to_100.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181027_projects_with_expiration_policy_enabled_with_keep_n_set_to_100.yml) Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_keep_n_set_to_25` -Missing description +A count of projects with the cleanup policy set to keep 25 tags -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181024_projects_with_expiration_policy_enabled_with_keep_n_set_to_25.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181024_projects_with_expiration_policy_enabled_with_keep_n_set_to_25.yml) Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_keep_n_set_to_5` -Missing description +A count of projects with the cleanup policy set to keep 5 tags -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181020_projects_with_expiration_policy_enabled_with_keep_n_set_to_5.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181020_projects_with_expiration_policy_enabled_with_keep_n_set_to_5.yml) Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_keep_n_set_to_50` -Missing description +A count of projects with the cleanup policy set to keep 50 tags -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181025_projects_with_expiration_policy_enabled_with_keep_n_set_to_50.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181025_projects_with_expiration_policy_enabled_with_keep_n_set_to_50.yml) Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_keep_n_unset` -Missing description +A count of projects with the cleanup policy with the number of tags to keep unset -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181046_projects_with_expiration_policy_enabled_with_keep_n_unset.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181046_projects_with_expiration_policy_enabled_with_keep_n_unset.yml) Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_older_than_set_to_14d` -Missing description +A count of projects with the cleanup policy set delete tags older than 14 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181040_projects_with_expiration_policy_enabled_with_older_than_set_to_14d.yml) @@ -5456,11 +5432,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_older_than_set_to_30d` -Missing description +A count of projects with the cleanup policy set delete tags older than 30 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181042_projects_with_expiration_policy_enabled_with_older_than_set_to_30d.yml) @@ -5468,11 +5444,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_older_than_set_to_7d` -Missing description +A count of projects with the cleanup policy set delete tags older than 7 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181038_projects_with_expiration_policy_enabled_with_older_than_set_to_7d.yml) @@ -5480,11 +5456,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_older_than_set_to_90d` -Missing description +A count of projects with the cleanup policy set delete tags older than 90 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181044_projects_with_expiration_policy_enabled_with_older_than_set_to_90d.yml) @@ -5492,11 +5468,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_expiration_policy_enabled_with_older_than_unset` -Missing description +A count of projects with the cleanup policy with the number of tags to delete unset [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181048_projects_with_expiration_policy_enabled_with_older_than_unset.yml) @@ -5504,11 +5480,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_packages` -Projects with package registry configured +Projects with package registry enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181011_projects_with_packages.yml) @@ -5516,7 +5492,7 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_prometheus_alerts` @@ -5524,9 +5500,9 @@ Projects with Prometheus alerting enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175019_projects_with_prometheus_alerts.yml) -Group: `group::apm` +Group: `group::monitor` -Status: `data_available` +Status: `removed` Tiers: `free` @@ -5666,13 +5642,13 @@ Tiers: `ultimate` Count of requirements created -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175028_requirements_created.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175028_requirements_created.yml) Group: `group::certify` Status: `data_available` -Tiers: `free` +Tiers: `ultimate` ### `counts.requirements_with_test_report` @@ -5796,7 +5772,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.static_site_editor_commits` -Count of commits created via Static Site Editor +Count of commits created from the Static Site Editor [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180301_static_site_editor_commits.yml) @@ -5804,7 +5780,7 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.static_site_editor_merge_requests` @@ -5816,11 +5792,11 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.static_site_editor_views` -Missing description +Count of Static Site Editor views [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180259_static_site_editor_views.yml) @@ -6012,15 +5988,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.templates_datadog_active` -Missing description +Count of active service templates for Datadog [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182551_templates_datadog_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.templates_discord_active` @@ -6060,15 +6036,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.templates_ewm_active` -Missing description +Count of active service templates for EWM [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182618_templates_ewm_active.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.templates_external_wiki_active` @@ -6098,13 +6074,13 @@ Tiers: `free`, `premium`, `ultimate` Count of active service templates for GitHub -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175851_templates_github_active.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175851_templates_github_active.yml) Group: `group::ecosystem` Status: `data_available` -Tiers: `free`, `premium`, `ultimate` +Tiers: `premium`, `ultimate` ### `counts.templates_hangouts_chat_active` @@ -6204,27 +6180,27 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.templates_mock_ci_active` -Missing description +Count of active service templates for Mock CI [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182726_templates_mock_ci_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.templates_mock_monitoring_active` -Missing description +Count of active service templates for Mock Monitoring [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182738_templates_mock_monitoring_active.yml) -Group: `` +Group: `group::ecosystem` -Status: `data_available` +Status: `removed` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.templates_packagist_active` @@ -6420,7 +6396,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.user_preferences_group_overview_details` -Count of users who set personal preference to see Details on Group overview page +Count of users who set personal preference to see Details on Group information page [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182203_user_preferences_group_overview_details.yml) @@ -6432,7 +6408,7 @@ Tiers: `ultimate` ### `counts.user_preferences_group_overview_security_dashboard` -Count of users who set personal preference to see Security Dashboard on Group overview page +Count of users who set personal preference to see Security Dashboard on Group information page [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182205_user_preferences_group_overview_security_dashboard.yml) @@ -6444,7 +6420,7 @@ Tiers: `ultimate` ### `counts.user_preferences_user_gitpod_enabled` -Count all users with their GitPod setting enabled +Count of users with the GitPod integration enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180304_user_preferences_user_gitpod_enabled.yml) @@ -6468,7 +6444,7 @@ Tiers: `free` ### `counts.web_ide_commits` -Count of Commits made from Web IDE +Count of commits made from the Web IDE [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180242_web_ide_commits.yml) @@ -6480,7 +6456,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.web_ide_merge_requests` -Count of merge requests created from Web IDE +Count of merge requests created from the Web IDE [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180246_web_ide_merge_requests.yml) @@ -6492,7 +6468,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.web_ide_pipelines` -Count of Pipeline tab views in Web IDE +Count of Pipeline tab views in the Web IDE [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180252_web_ide_pipelines.yml) @@ -6504,7 +6480,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.web_ide_previews` -Count of Live Preview tab views in Web IDE +Count of Live Preview tab views in the Web IDE [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180248_web_ide_previews.yml) @@ -6516,7 +6492,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.web_ide_terminals` -Count of Web Terminal Tab views in Web IDE +Count of Web Terminal tab views in the Web IDE [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180250_web_ide_terminals.yml) @@ -6528,7 +6504,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.web_ide_views` -Count of Views of the Web IDE +Count of views of the Web IDE [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180244_web_ide_views.yml) @@ -6540,39 +6516,39 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.wiki_pages_create` -Missing description +Count of all Wiki pages created [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180734_wiki_pages_create.yml) -Group: `group::knowledge` +Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.wiki_pages_delete` -Missing description +Count of all Wiki pages deleted [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180738_wiki_pages_delete.yml) -Group: `group::knowledge` +Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.wiki_pages_update` -Missing description +Count of all Wiki page updates [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180736_wiki_pages_update.yml) -Group: `group::knowledge` +Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.wiki_pages_view` @@ -6594,7 +6570,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -6606,7 +6582,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -6618,7 +6594,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -6720,7 +6696,7 @@ Tiers: `free` ### `counts_monthly.packages` -Monthly count of Packages +A monthly count of packages published to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216181050_packages.yml) @@ -6728,11 +6704,11 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts_monthly.personal_snippets` -Monthly count of Personal Snippets +Monthly count of personal Snippets [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180308_personal_snippets.yml) @@ -6744,7 +6720,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts_monthly.project_snippets` -Monthly count of Project Snippets +Monthly count of project Snippets [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180310_project_snippets.yml) @@ -6754,6 +6730,18 @@ Status: `data_available` Tiers: `free`, `premium`, `ultimate` +### `counts_monthly.projects` + +Count number of projects created monthly + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210514141518_monthly_projects_creation.yml) + +Group: `group::project management` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `counts_monthly.projects_with_alerts_created` Monthly count of unique projects with HTTP alerting enabled @@ -6798,7 +6786,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -6810,7 +6798,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -6822,7 +6810,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -6936,15 +6924,15 @@ Tiers: `free`, `premium`, `ultimate` ### `dependency_proxy_enabled` -Whether dependency proxy is enabled +A count of projects where the dependency proxy is enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210204124900_dependency_proxy_enabled.yml) -Group: `group::product intelligence` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `edition` @@ -6984,15 +6972,15 @@ Tiers: `premium`, `ultimate` ### `git.version` -Missing description +Information about Git version [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/20210216183237_version.yml) -Group: `` +Group: `group::distribution` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `gitaly.clusters` @@ -7080,7 +7068,7 @@ Tiers: `free`, `premium`, `ultimate` ### `gitpod_enabled` -Whether gitpod is enabled in the instance +Whether Gitpod is enabled in the instance [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216180314_gitpod_enabled.yml) @@ -7108,19 +7096,19 @@ Whether gravatar is enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210204124904_gravatar_enabled.yml) -Group: `group::product intelligence` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `historical_max_users` -The maximum active user count. Active is defined in UsersStatistics model. +The peak active user count. Active is defined in UsersStatistics model. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124835_historical_max_users.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7146,7 +7134,7 @@ Whether or not ModSecurity is enabled within Ingress Group: `group::container security` -Status: `deprecated` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -7186,13 +7174,25 @@ Status: `data_available` Tiers: `free` +### `license_billable_users` + +Number of all billable users (active users excluding bots and guests). + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210531204603_license_billable_users.yml) + +Group: `group::product intelligence` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `license_expires_at` The date the license ends [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124847_license_expires_at.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7204,7 +7204,7 @@ The ID of the license [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124833_license_id.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7212,15 +7212,15 @@ Tiers: `premium`, `ultimate` ### `license_md5` -The license key of the GitLab instance +The MD5 hash of license key of the GitLab instance [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124831_license_md5.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` -Tiers: `free`, `premium`, `ultimate` +Tiers: `premium`, `ultimate` ### `license_plan` @@ -7228,7 +7228,7 @@ The plan of the GitLab license [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124849_license_plan.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7240,7 +7240,7 @@ The date the license starts [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124845_license_starts_at.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7252,7 +7252,7 @@ Licese zuora_subscription_id [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124852_license_subscription_id.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7262,9 +7262,9 @@ Tiers: `premium`, `ultimate` Whether this is a trial license or not -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/settings/20210204124851_license_trial.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124851_license_trial.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7272,23 +7272,23 @@ Tiers: `premium`, `ultimate` ### `license_trial_ends_on` -Date the license ends on +Date the trial license ends on -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/20210204124926_license_trial_ends_on.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124926_license_trial_ends_on.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `license_user_count` -The number of users included in the license +The number of seats included in the license [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124843_license_user_count.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7300,7 +7300,7 @@ Company on the GitLab license [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124841_company.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7312,7 +7312,7 @@ Email on the GitLab license [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124839_email.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7324,7 +7324,7 @@ Name on the GitLab license [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210204124837_name.yml) -Group: `group::product intelligence` +Group: `group::license` Status: `data_available` @@ -7348,11 +7348,11 @@ Whether Mattermost is enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210204124908_mattermost_enabled.yml) -Group: `group::product intelligence` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `object_store.artifacts.enabled` @@ -7676,7 +7676,7 @@ Group: `group::product intelligence` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `prometheus_metrics_enabled` @@ -7688,7 +7688,7 @@ Group: `group::product intelligence` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `recorded_at` @@ -7724,7 +7724,7 @@ Group: `group::product intelligence` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `redis_hll_counters.analytics.analytics_total_unique_counts_monthly` @@ -7926,7 +7926,7 @@ Counts visits to DevOps Adoption page per month Group: `group::optimize` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -7938,7 +7938,7 @@ Counts visits to DevOps Adoption page per week Group: `group::optimize` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -8166,7 +8166,7 @@ Counts visits to DevOps Adoption page per month Group: `group::optimize` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -8178,7 +8178,7 @@ Counts visits to DevOps Adoption page per week Group: `group::optimize` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -8208,27 +8208,27 @@ Tiers: ### `redis_hll_counters.ci_templates.ci_templates_total_unique_counts_monthly` -Missing description +Total count of pipelines runs [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml) -Group: `` +Group: `group::configure` -Status: `data_available` +Status: `broken` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.ci_templates_total_unique_counts_weekly` -Missing description +Total count of pipelines runs -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml) -Group: `` +Group: `group::configure` -Status: `data_available` +Status: `broken` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_5_min_production_app_monthly` @@ -8614,6 +8614,30 @@ Status: `data_available` Tiers: `free`, `premium`, `ultimate` +### `redis_hll_counters.code_review.i_code_review_click_diff_view_setting_monthly` + +Count of users clicking diff view setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210607113556_i_code_review_click_diff_view_setting_monthly.yml) + +Group: `group::code review` + +Status: `data_available` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_click_diff_view_setting_weekly` + +Count of users clicking diff view setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210607113552_i_code_review_click_diff_view_setting_weekly.yml) + +Group: `group::code review` + +Status: `data_available` + +Tiers: `free`, `premium`, `ultimate` + ### `redis_hll_counters.code_review.i_code_review_click_file_browser_setting_monthly` Count of users clicking merge request file browser setting @@ -8622,7 +8646,7 @@ Count of users clicking merge request file browser setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8634,7 +8658,7 @@ Count of users with merge request file list setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8646,7 +8670,7 @@ Count of users clicking single file mode setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8658,7 +8682,7 @@ Count of users clicking single file mode setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8670,7 +8694,7 @@ Count of users clicking merge request whitespae setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8682,7 +8706,7 @@ Count of users clicking merge request whitespae setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8694,7 +8718,7 @@ Count of users with show whitespace disabled Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8706,7 +8730,7 @@ Count of users with show whitespace disabled Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8718,7 +8742,7 @@ Count of users with single mode disabled Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8730,7 +8754,7 @@ Count of users with single mode disabled Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8742,7 +8766,7 @@ Count of users with show whitespace enabled Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8754,7 +8778,7 @@ Count of users with show whitespace enabled Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8766,7 +8790,7 @@ Count of users with single file mode enabled Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8778,7 +8802,7 @@ Count of users with single file mode enabled Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8790,7 +8814,7 @@ Count of users with merge request view type as inline Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8802,7 +8826,7 @@ Count of users with merge request view type as inline Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8814,7 +8838,7 @@ Count of users with merge request view type as parallel Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8826,7 +8850,7 @@ Count of users with merge request view type as parallel Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8886,7 +8910,7 @@ Count of users with merge request file list setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8898,7 +8922,7 @@ Count of users with merge request file list setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8910,7 +8934,7 @@ Count of users with merge request file tree setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -8922,7 +8946,7 @@ Count of users with merge request file tree setting Group: `group::code review` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -9382,6 +9406,30 @@ Status: `data_available` Tiers: `free`, `premium`, `ultimate` +### `redis_hll_counters.code_review.i_code_review_user_load_conflict_ui_monthly` + +Count of unique users per week who load the conflict resolution page + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210514013549_i_code_review_user_load_conflict_ui_monthly.yml) + +Group: `group::code review` + +Status: `data_available` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_user_load_conflict_ui_weekly` + +Count of unique users per week who load the conflict resolution page + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210514013544_i_code_review_user_load_conflict_ui_weekly.yml) + +Group: `group::code review` + +Status: `data_available` + +Tiers: `free`, `premium`, `ultimate` + ### `redis_hll_counters.code_review.i_code_review_user_marked_as_draft_monthly` Count of unique users per month who mark a merge request as a draft @@ -9598,6 +9646,30 @@ Status: `data_available` Tiers: `free`, `premium`, `ultimate` +### `redis_hll_counters.code_review.i_code_review_user_resolve_conflict_monthly` + +Count of unique users per week who attempt to resolve a conflict through the ui + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210514013545_i_code_review_user_resolve_conflict_monthly.yml) + +Group: `group::code review` + +Status: `data_available` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_user_resolve_conflict_weekly` + +Count of unique users per week who attempt to resolve a conflict through the ui + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210514013545_i_code_review_user_resolve_conflict_weekly.yml) + +Group: `group::code review` + +Status: `data_available` + +Tiers: `free`, `premium`, `ultimate` + ### `redis_hll_counters.code_review.i_code_review_user_resolve_thread_monthly` Count of unique users per month who resolve a thread in a merge request @@ -10008,271 +10080,295 @@ Tiers: ### `redis_hll_counters.deploy_token_packages.deploy_token_packages_total_unique_counts_monthly` -Missing description +A monthly count of packages published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184850_deploy_token_packages_total_unique_counts_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.deploy_token_packages_total_unique_counts_weekly` -Missing description +A weekly count of packages published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184848_deploy_token_packages_total_unique_counts_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184848_deploy_token_packages_total_unique_counts_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_composer_deploy_token_monthly` -Missing description +A monthly count of Composer packages published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184806_i_package_composer_deploy_token_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_composer_deploy_token_weekly` -Missing description +A weekly count of Composer packages published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184805_i_package_composer_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184805_i_package_composer_deploy_token_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_conan_deploy_token_monthly` -Missing description +A monthly count of Conan packages published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184810_i_package_conan_deploy_token_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_conan_deploy_token_weekly` -Missing description +A weekly count of Conan packages published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184808_i_package_conan_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184808_i_package_conan_deploy_token_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_container_deploy_token_monthly` -Missing description +A monthly count of container images published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184814_i_package_container_deploy_token_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_container_deploy_token_weekly` -Missing description +A weekly count of container images published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184812_i_package_container_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184812_i_package_container_deploy_token_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_debian_deploy_token_monthly` -Missing description +A monthly count of Debian packages published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184818_i_package_debian_deploy_token_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_debian_deploy_token_weekly` -Missing description +A weekly count of Debian packages published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184816_i_package_debian_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184816_i_package_debian_deploy_token_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_generic_deploy_token_monthly` -Missing description +A monthly count of generic packages published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184822_i_package_generic_deploy_token_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `broken` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_generic_deploy_token_weekly` -Missing description +A weekly count of generic packages published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184820_i_package_generic_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184820_i_package_generic_deploy_token_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_golang_deploy_token_monthly` -Missing description +A monthly count of Go modules published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184826_i_package_golang_deploy_token_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_golang_deploy_token_weekly` -Missing description +A weekly count of Go modules published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184824_i_package_golang_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184824_i_package_golang_deploy_token_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.deploy_token_packages.i_package_helm_deploy_token_monthly` + +Distinct Helm pakages deployed in recent 28 days + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210517074859_i_package_helm_deploy_token_monthly.yml) + +Group: `group::package` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.deploy_token_packages.i_package_helm_deploy_token_weekly` + +Distinct Helm pakages deployed in recent 7 days + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210517074851_i_package_helm_deploy_token_weekly.yml) + +Group: `group::package` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_maven_deploy_token_monthly` -Missing description +A monthly count of Maven packages published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184830_i_package_maven_deploy_token_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_maven_deploy_token_weekly` -Missing description +A weekly count of Maven packages published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184828_i_package_maven_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184828_i_package_maven_deploy_token_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_npm_deploy_token_monthly` -Missing description +A monthly count of npm packages published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184834_i_package_npm_deploy_token_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_npm_deploy_token_weekly` -Missing description +A weekly count of npm packages published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184832_i_package_npm_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184832_i_package_npm_deploy_token_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_nuget_deploy_token_monthly` -Missing description +A monthly count of NuGet packages published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184838_i_package_nuget_deploy_token_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_nuget_deploy_token_weekly` -Missing description +A weekly count of NuGet packages published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184836_i_package_nuget_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184836_i_package_nuget_deploy_token_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_pypi_deploy_token_monthly` -Missing description +A monthly count of PyPI packages published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184842_i_package_pypi_deploy_token_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_pypi_deploy_token_weekly` -Missing description +A weekly count of Python packages published to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184840_i_package_pypi_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184840_i_package_pypi_deploy_token_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_rubygems_deploy_token_monthly` -Distinct user count events for RubyGems packages in recent 28 days +Distinct count events for RubyGems packages published using a Deploy token in recent 28 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210303154626_i_package_rubygems_deploy_token_monthly.yml) @@ -10284,7 +10380,7 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_rubygems_deploy_token_weekly` -Distinct RubyGems pakages deployed in recent 7 days +A weekly count of distinct RubyGems packages published using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210303154624_i_package_rubygems_deploy_token_weekly.yml) @@ -10296,27 +10392,27 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_tag_deploy_token_monthly` -Missing description +A monthly count of package tags published to the registry using a deploy token [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184846_i_package_tag_deploy_token_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_tag_deploy_token_weekly` -Missing description +A weekly count of users that have published a package tag to the registry using a deploy token -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184844_i_package_tag_deploy_token_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184844_i_package_tag_deploy_token_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.deploy_token_packages.i_package_terraform_module_deploy_token_monthly` @@ -10326,7 +10422,7 @@ Number of distinct users authorized via deploy token creating Terraform Module p Group: `group::configure` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -10338,129 +10434,129 @@ Number of distinct users authorized via deploy token creating Terraform Module p Group: `group::configure` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ecosystem.ecosystem_total_unique_counts_monthly` -Missing description +Number of users performing actions on Jira issues by month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184957_ecosystem_total_unique_counts_monthly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ecosystem.ecosystem_total_unique_counts_weekly` -Missing description +Number of users performing actions on Jira issues by week -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184955_ecosystem_total_unique_counts_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184955_ecosystem_total_unique_counts_weekly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ecosystem.i_ecosystem_jira_service_close_issue_monthly` -Missing description +Number of users closing Jira issues by month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184941_i_ecosystem_jira_service_close_issue_monthly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ecosystem.i_ecosystem_jira_service_close_issue_weekly` -Missing description +Number of users closing Jira issues by week -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184939_i_ecosystem_jira_service_close_issue_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184939_i_ecosystem_jira_service_close_issue_weekly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ecosystem.i_ecosystem_jira_service_create_issue_monthly` -Missing description +Number of users creating Jira issues by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184953_i_ecosystem_jira_service_create_issue_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216184953_i_ecosystem_jira_service_create_issue_monthly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `redis_hll_counters.ecosystem.i_ecosystem_jira_service_create_issue_weekly` -Missing description +Number of users creating Jira issues by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184951_i_ecosystem_jira_service_create_issue_weekly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `redis_hll_counters.ecosystem.i_ecosystem_jira_service_cross_reference_monthly` -Missing description +Number of users that cross-referenced Jira issues by month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184945_i_ecosystem_jira_service_cross_reference_monthly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ecosystem.i_ecosystem_jira_service_cross_reference_weekly` -Missing description +Number of users that cross-referenced Jira issues by week -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184943_i_ecosystem_jira_service_cross_reference_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184943_i_ecosystem_jira_service_cross_reference_weekly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ecosystem.i_ecosystem_jira_service_list_issues_monthly` -Missing description +Count of Jira Issue List visits by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184949_i_ecosystem_jira_service_list_issues_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216184949_i_ecosystem_jira_service_list_issues_monthly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `redis_hll_counters.ecosystem.i_ecosystem_jira_service_list_issues_weekly` -Missing description +Count of Jira Issue List visits by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184947_i_ecosystem_jira_service_list_issues_weekly.yml) -Group: `` +Group: `group::ecosystem` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `redis_hll_counters.ecosystem.i_ecosystem_slack_service_confidential_issue_notification_monthly` @@ -10678,6 +10774,30 @@ Status: `data_available` Tiers: `free`, `premium`, `ultimate` +### `redis_hll_counters.epic_boards_usage.epic_boards_usage_total_unique_counts_monthly` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210507171840_epic_boards_usage_total_unique_counts_monthly.yml) + +Group: `` + +Status: `data_available` + +Tiers: `ultimate` + +### `redis_hll_counters.epic_boards_usage.epic_boards_usage_total_unique_counts_weekly` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210507171838_epic_boards_usage_total_unique_counts_weekly.yml) + +Group: `` + +Status: `data_available` + +Tiers: `ultimate` + ### `redis_hll_counters.epic_boards_usage.g_project_management_users_creating_epic_boards_monthly` Count of MAU creating epic boards @@ -10686,7 +10806,7 @@ Count of MAU creating epic boards Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10698,7 +10818,7 @@ Count of WAU creating epic boards Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10710,7 +10830,7 @@ Count of MAU updating epic board names Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10722,7 +10842,7 @@ Count of WAU updating epic board names Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10734,7 +10854,7 @@ Count of MAU viewing epic boards Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10746,7 +10866,7 @@ Count of WAU viewing epic boards Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10758,7 +10878,7 @@ Total monthly users count for epics_usage Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10770,7 +10890,7 @@ Total weekly users count for epics_usage Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10782,7 +10902,7 @@ Counts of MAU closing epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10830,7 +10950,7 @@ Count of MAU cross referencing epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10842,7 +10962,7 @@ Counts of WAU cross referencing epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10854,7 +10974,7 @@ Count of MAU destroying epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10866,7 +10986,7 @@ Count of WAU destroying epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10878,7 +10998,7 @@ Count of MAU adding issues to epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10890,7 +11010,7 @@ Count of WAU adding issues to epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10902,7 +11022,7 @@ Counts of MAU moving epic issues between projects Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10914,7 +11034,7 @@ Counts of WAU moving epic issues between projects Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10926,7 +11046,7 @@ Count of MAU removing issues from epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10938,7 +11058,7 @@ Counts of WAU removing issues from epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10950,7 +11070,7 @@ Counts of MAU closing epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10962,7 +11082,7 @@ Counts of WAU re-opening epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10974,7 +11094,7 @@ Count of MAU chaging the epic lables Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10986,7 +11106,7 @@ Count of WAU chaging the epic lables Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -10998,7 +11118,7 @@ Count of MAU promoting issues to epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11010,7 +11130,7 @@ Counts of WAU promoting issues to epics Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11022,7 +11142,7 @@ Counts of MAU awarding emoji on epic Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11034,7 +11154,7 @@ Counts of WAU awarding emoji on epic Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11070,7 +11190,7 @@ Counts of MAU destroying epic notes Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11082,10 +11202,34 @@ Counts of WAU destroying epic notes Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` +### `redis_hll_counters.epics_usage.g_project_management_users_epic_issue_added_from_epic_monthly` + +Number of users creating an issue from an epic + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210608191652_g_project_management_users_epic_issue_added_from_epic_monthly.yml) + +Group: `group::product planning` + +Status: `data_available` + +Tiers: `premium` + +### `redis_hll_counters.epics_usage.g_project_management_users_epic_issue_added_from_epic_weekly` + +Number of users creating an issue from an epic + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210608191647_g_project_management_users_epic_issue_added_from_epic_weekly.yml) + +Group: `group::product planning` + +Status: `data_available` + +Tiers: `premium` + ### `redis_hll_counters.epics_usage.g_project_management_users_removing_epic_emoji_monthly` Counts of MAU removing emoji on epic @@ -11094,7 +11238,7 @@ Counts of MAU removing emoji on epic Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11106,7 +11250,7 @@ Counts of WAU removing emoji on epic Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11118,7 +11262,7 @@ Count of MAU making epics confidential Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11130,7 +11274,7 @@ Count of WAU making epics confidential Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11142,7 +11286,7 @@ Counts of MAU setting epic due date as inherited Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11154,7 +11298,7 @@ Counts of WAU setting epic due date as fixed Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11166,7 +11310,7 @@ Counts of MAU setting epic due date as inherited Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11178,7 +11322,7 @@ Counts of WAU setting epic due date as inherited Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11190,7 +11334,7 @@ Counts of MAU setting epic start date as fixed Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11202,7 +11346,7 @@ Counts of WAU setting epic start date as fixed Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11214,7 +11358,7 @@ Counts of MAU setting epic start date as inherited Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11226,7 +11370,7 @@ Counts of WAU setting epic start date as inherited Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11238,7 +11382,7 @@ Count of MAU making epics visible Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11250,7 +11394,7 @@ Count of WAU making epics visible Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11262,7 +11406,7 @@ Counts of MAU changing epic descriptions Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11274,7 +11418,7 @@ Counts of WAU changing epic descriptions Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11286,7 +11430,7 @@ Counts of MAU updating epic notes Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11298,7 +11442,7 @@ Counts of WAU updating epic notes Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11310,7 +11454,7 @@ Counts of MAU updating parent on epic Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11322,7 +11466,7 @@ Counts of WAU updating parent on epic Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11334,7 +11478,7 @@ Counts of MAU changing epic titles Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11346,7 +11490,7 @@ Counts of WAU changing epic titles Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11358,7 +11502,7 @@ Counts of MAU manually updating fixed due date Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11370,7 +11514,7 @@ Counts of WAU manually updating fixed due date Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11382,7 +11526,7 @@ Counts of MAU manually updating fixed start date Group: `group::product planning` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11394,13 +11538,61 @@ Counts of WAU manually updating fixed start date Group: `group::product planning` -Status: `implemented` +Status: `data_available` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epics_usage.project_management_users_checking_epic_task_monthly` + +Counts of MAU checking epic task + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210421080207_g_project_management_users_checking_epic_task_monthly.yml) + +Group: `group::product planning` + +Status: `data_available` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epics_usage.project_management_users_checking_epic_task_weekly` + +Counts of WAU checking epic task + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210421075943_g_project_management_users_checking_epic_task_weekly.yml) + +Group: `group::product planning` + +Status: `data_available` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epics_usage.project_management_users_unchecking_epic_task_monthly` + +Counts of MAU unchecking epic task + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210421102516_g_project_management_users_unchecking_epic_task_monthly.yml) + +Group: `group::product planning` + +Status: `data_available` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epics_usage.project_management_users_unchecking_epic_task_weekly` + +Counts of WAU unchecking epic task + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210421102812_g_project_management_users_unchecking_epic_task_weekly.yml) + +Group: `group::product planning` + +Status: `data_available` Tiers: `premium`, `ultimate` ### `redis_hll_counters.ide_edit.g_edit_by_sfe_monthly` -Missing description +Number of users editing a file from the single file editor [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180334_g_edit_by_sfe_monthly.yml) @@ -11408,23 +11600,23 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ide_edit.g_edit_by_sfe_weekly` -Missing description +Weekly number of users editing from the single file editor -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216180332_g_edit_by_sfe_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216180332_g_edit_by_sfe_weekly.yml) Group: `group::editor` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ide_edit.g_edit_by_snippet_ide_monthly` -Missing description +Count of monthly edits to a snippet [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180338_g_edit_by_snippet_ide_monthly.yml) @@ -11432,47 +11624,47 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ide_edit.g_edit_by_snippet_ide_weekly` -Missing description +Weekly number of users editing Snippets -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216180336_g_edit_by_snippet_ide_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216180336_g_edit_by_snippet_ide_weekly.yml) Group: `group::editor` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ide_edit.g_edit_by_sse_monthly` -Missing description +Number of user editing files using the Static Site Editor [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184024_g_edit_by_sse_monthly.yml) -Group: `` +Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ide_edit.g_edit_by_sse_weekly` -Missing description +Weekly number of users editing using the Static Site Editor -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184022_g_edit_by_sse_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184022_g_edit_by_sse_weekly.yml) -Group: `` +Group: `group::editor` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ide_edit.g_edit_by_web_ide_monthly` -Missing description +Number of users editing a file from the Web IDE [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180330_g_edit_by_web_ide_monthly.yml) @@ -11480,23 +11672,23 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ide_edit.g_edit_by_web_ide_weekly` -Missing description +Weekly number of users editing using the Web IDE -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216180328_g_edit_by_web_ide_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216180328_g_edit_by_web_ide_weekly.yml) Group: `group::editor` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ide_edit.ide_edit_total_unique_counts_monthly` -Missing description +Count of unique users per month who edited a file from the Web IDE [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180341_ide_edit_total_unique_counts_monthly.yml) @@ -11504,19 +11696,19 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ide_edit.ide_edit_total_unique_counts_weekly` -Missing description +Weekly number of users editing a file using the Web IDE -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216180339_ide_edit_total_unique_counts_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216180339_ide_edit_total_unique_counts_weekly.yml) Group: `group::editor` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.incident_management.incident_management_alert_assigned_monthly` @@ -11910,7 +12102,7 @@ Count of unique users to receive a notification while on-call Group: `group::monitor` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -11922,7 +12114,7 @@ Count of unique users to receive a notification while on-call Group: `group::monitor` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -12744,27 +12936,27 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.pipeline_authoring.o_pipeline_authoring_unique_users_committing_ciconfigfile_monthly` -Missing description +Monthly unique user count doing commits which contains the CI config file [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184303_o_pipeline_authoring_unique_users_committing_ciconfigfile_monthly.yml) -Group: `` +Group: `group::pipeline authoring` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.pipeline_authoring.o_pipeline_authoring_unique_users_committing_ciconfigfile_weekly` -Missing description +Weekly unique user count doing commits which contains the CI config file -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184301_o_pipeline_authoring_unique_users_committing_ciconfigfile_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184301_o_pipeline_authoring_unique_users_committing_ciconfigfile_weekly.yml) -Group: `` +Group: `group::pipeline authoring` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.pipeline_authoring.o_pipeline_authoring_unique_users_pushing_mr_ciconfigfile_monthly` @@ -12798,7 +12990,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -12810,7 +13002,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -14550,7 +14742,7 @@ Count of expanding the security report widget Group: `group::static analysis` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -14562,33 +14754,33 @@ Count of expanding the security report widget Group: `group::static analysis` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.snippets.i_snippets_show_monthly` -Missing description +Monthly number of users viewing snippets [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184255_i_snippets_show_monthly.yml) -Group: `` +Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.snippets.i_snippets_show_weekly` -Missing description +Weekly number of users viewing snippets -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184253_i_snippets_show_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184253_i_snippets_show_weekly.yml) -Group: `` +Group: `group::editor` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.design_action_monthly` @@ -14910,7 +15102,7 @@ Unique users that expand the test summary merge request widget by month Group: `group::testing` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -14922,7 +15114,7 @@ Unique users that expand the test summary merge request widget by week Group: `group::testing` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -15006,7 +15198,7 @@ Count of expanding the accessibility report widget Group: `group::testing` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -15018,7 +15210,7 @@ Count of expanding the accessibility report widget Group: `group::testing` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -15030,7 +15222,7 @@ Count of expanding the code quality widget Group: `group::testing` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -15042,253 +15234,277 @@ Count of expanding the code quality widget Group: `group::testing` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_composer_user_monthly` -Missing description +A monthly count of users that have published a Composer package to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184854_i_package_composer_user_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_composer_user_weekly` -Missing description +A weekly count of users that have published a Composer package to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184852_i_package_composer_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184852_i_package_composer_user_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_conan_user_monthly` -Missing description +A monthly count of users that have published a Conan package to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184858_i_package_conan_user_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_conan_user_weekly` -Missing description +A weekly count of users that have published a Conan package to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184856_i_package_conan_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184856_i_package_conan_user_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_container_user_monthly` -Missing description +A monthly count of users that have published a container image to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184902_i_package_container_user_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_container_user_weekly` -Missing description +A weekly count of users that have published a container image to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184900_i_package_container_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184900_i_package_container_user_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_debian_user_monthly` -Missing description +A monthly count of users that have published a Debian package to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184906_i_package_debian_user_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_debian_user_weekly` -Missing description +A weekly count of users that have published a Debian package to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184904_i_package_debian_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184904_i_package_debian_user_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_generic_user_monthly` -Missing description +A monthly count of users that have published a generic package to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184910_i_package_generic_user_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `broken` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_generic_user_weekly` -Missing description +A weekly count of users that have published a generic package to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184908_i_package_generic_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184908_i_package_generic_user_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `broken` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_golang_user_monthly` -Missing description +A monthly count of users that have published a Go moduleto the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184913_i_package_golang_user_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_golang_user_weekly` -Missing description +A weekly count of users that have published a Go module to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184911_i_package_golang_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184911_i_package_golang_user_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.user_packages.i_package_helm_user_monthly` + +Distinct user count events for Helm packages in recent 28 days + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210517075259_i_package_helm_user_monthly.yml) + +Group: `group::package` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.user_packages.i_package_helm_user_weekly` + +Distinct user count events for Helm packages in recent 7 days + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210517075252_i_package_helm_user_weekly.yml) + +Group: `group::package` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_maven_user_monthly` -Missing description +A monthly count of users that have published a Maven package to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184917_i_package_maven_user_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_maven_user_weekly` -Missing description +A weekly count of users that have published a Maven package to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184916_i_package_maven_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184916_i_package_maven_user_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_npm_user_monthly` -Missing description +A monthly count of users that have published an npm package to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184921_i_package_npm_user_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_npm_user_weekly` -Missing description +A weekly count of users that have published an npm package to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184919_i_package_npm_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184919_i_package_npm_user_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_nuget_user_monthly` -Missing description +A monthly count of users that have published a NuGet package to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184925_i_package_nuget_user_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_nuget_user_weekly` -Missing description +A weekly count of users that have published a NuGet package to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184923_i_package_nuget_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184923_i_package_nuget_user_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_pypi_user_monthly` -Missing description +A monthly count of users that have published a PyPI package to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184929_i_package_pypi_user_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_pypi_user_weekly` -Missing description +A weekly count of users that have published a Python package to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184927_i_package_pypi_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184927_i_package_pypi_user_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_rubygems_user_monthly` -Distinct user count events for RubyGems packages in recent 28 days +Distinct user count of RubyGems packages published in recent 28 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210303154654_i_package_rubygems_user_monthly.yml) @@ -15300,7 +15516,7 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_rubygems_user_weekly` -Distinct user count events for RubyGems packages in recent 7 days +A weekly count of distinct RubyGems packages published by a user [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210303154652_i_package_rubygems_user_weekly.yml) @@ -15312,27 +15528,27 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_tag_user_monthly` -Missing description +A monthly count of users that have published a package tag to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184933_i_package_tag_user_monthly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_tag_user_weekly` -Missing description +A weekly count of users that have published a package with a tag to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184931_i_package_tag_user_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184931_i_package_tag_user_weekly.yml) -Group: `` +Group: `group::package` -Status: `data_available` +Status: `deprecated` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.i_package_terraform_module_user_monthly` @@ -15342,7 +15558,7 @@ Number of distinct users creating Terraform Module packages in recent 28 days Group: `group::configure` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -15354,33 +15570,33 @@ Number of distinct users creating Terraform Module packages in recent 7 days Group: `group::configure` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.user_packages_total_unique_counts_monthly` -Missing description +A monthly count of users that have published a package to the registry [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184937_user_packages_total_unique_counts_monthly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.user_packages.user_packages_total_unique_counts_weekly` -Missing description +A weekly count of users that have published a package to the registry -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184935_user_packages_total_unique_counts_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184935_user_packages_total_unique_counts_weekly.yml) -Group: `` +Group: `group::package` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `reply_by_email_enabled` @@ -15388,11 +15604,11 @@ Whether incoming email is setup [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210204124916_reply_by_email_enabled.yml) -Group: `group::product intelligence` +Group: `group::certify` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `search_unique_visits.i_search_advanced` @@ -15462,7 +15678,7 @@ Gitaly application performance Group: `group::gitaly` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -15740,7 +15956,7 @@ Projects with Prometheus alerting enabled Group: `group::configure` -Status: `data_available` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -15986,7 +16202,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.snippets` -Snippets +Count of distinct author_id from snippets [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180316_snippets.yml) @@ -16068,6 +16284,18 @@ Status: `data_available` Tiers: `premium`, `ultimate` +### `usage_activity_by_stage.enablement.counts.geo_node_usage.git_push_event_count_weekly` + +Number of Git push events from Prometheus on the Geo secondary + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210604110603_git_push_event_count_weekly.yml) + +Group: `group::geo` + +Status: `data_available` + +Tiers: `premium`, `ultimate` + ### `usage_activity_by_stage.enablement.geo_secondary_web_oauth_users` Missing description @@ -16076,7 +16304,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -16112,7 +16340,7 @@ Total count of all custom compliance framework labels Group: `compliance` -Status: `implemented` +Status: `data_available` Tiers: `premium`, `ultimate` @@ -16166,15 +16394,15 @@ Tiers: `premium` ### `usage_activity_by_stage.manage.groups` -Missing description +Number of users who are group members. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180756_groups.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.groups_imported` @@ -16286,75 +16514,75 @@ Tiers: `free` ### `usage_activity_by_stage.manage.ldap_admin_sync_enabled` -Has the instance configured LDAP Admin Sync `https://docs.gitlab.com/ee/administration/auth/ldap/#administrator-sync`? +Has the instance configured [LDAP Admin Sync](https://docs.gitlab.com/ee/administration/auth/ldap/#administrator-sync) [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/settings/20210216180811_ldap_admin_sync_enabled.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.manage.ldap_group_sync_enabled` -Has the instance configured LDAP Group Sync `https://docs.gitlab.com/ee/administration/auth/ldap/#group-sync`? +Has the instance configured [LDAP Group Sync](https://docs.gitlab.com/ee/administration/auth/ldap/#group-sync) [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/settings/20210216180809_ldap_group_sync_enabled.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.manage.ldap_keys` -Missing description +Number of users creating keys synced as part of LDAP -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180800_ldap_keys.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216180800_ldap_keys.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.manage.ldap_servers` -Number of LDAP servers configured for the instance `https://docs.gitlab.com/ee/administration/auth/ldap/#multiple-ldap-servers` +Number of [LDAP servers configured for the instance](https://docs.gitlab.com/ee/administration/auth/ldap/#multiple-ldap-servers) [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216180807_ldap_servers.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.manage.ldap_users` -Missing description +Number of users that are linked to LDAP -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180801_ldap_users.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216180801_ldap_users.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.manage.omniauth_providers` -Missing description +Number of unique user logins using an OmniAuth provider [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183400_omniauth_providers.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.project_imports.bitbucket` @@ -16366,7 +16594,7 @@ Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.project_imports.bitbucket_server` @@ -16378,7 +16606,7 @@ Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.project_imports.git` @@ -16390,7 +16618,7 @@ Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.project_imports.gitea` @@ -16402,7 +16630,7 @@ Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.project_imports.github` @@ -16414,7 +16642,7 @@ Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.project_imports.gitlab` @@ -16426,7 +16654,7 @@ Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.project_imports.gitlab_migration` @@ -16438,7 +16666,7 @@ Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.project_imports.gitlab_project` @@ -16450,7 +16678,7 @@ Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.project_imports.manifest` @@ -16462,7 +16690,19 @@ Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` + +### `usage_activity_by_stage.manage.project_imports.total` + +Count number of projects imported monthly + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210514141520_project_imports_total.yml) + +Group: `group::import` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.projects_imported.bitbucket` @@ -16598,87 +16838,87 @@ Tiers: `free` ### `usage_activity_by_stage.manage.user_auth_by_provider.google_oauth2` -Missing description +Number of unique user logins using Google OAuth authentication [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183410_google_oauth2.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.user_auth_by_provider.standard` -Missing description +Number of unique user logins using password authentication [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183408_standard.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.user_auth_by_provider.two-factor` -Missing description +Number of unique user logins using two factor authentication [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183402_two-factor.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.user_auth_by_provider.two-factor-via-u2f-device` -Missing description +Number of unique user logins using two factor via a U2F device [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183404_two-factor-via-u2f-device.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.user_auth_by_provider.two-factor-via-webauthn-device` -Missing description +Number of unique user logins using two factor via a WebAuthn device [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183406_two-factor-via-webauthn-device.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.users_created` -Missing description +Number of users [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180758_users_created.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.manage.value_stream_management_customized_group_stages` -Missing description +Number of custom value stream analytics stages. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216180803_value_stream_management_customized_group_stages.yml) -Group: `group::manage` +Group: `group::optimize` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.monitor.clusters` @@ -16804,7 +17044,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.package.projects_with_packages` -Projects with package registry configured +Projects with package registry enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181055_projects_with_packages.yml) @@ -16812,7 +17052,7 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.plan.assignee_lists` @@ -17000,7 +17240,7 @@ Count creator_id from projects with repository mirroring enabled. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181934_projects_mirrored_with_pipelines_enabled.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -17080,7 +17320,7 @@ Tiers: ### `usage_activity_by_stage.secure.dependency_scanning_scans` -Counts dependency scanning jobs +Total number of users running Dependency Scanning Scans [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175220_dependency_scanning_scans.yml) @@ -17176,7 +17416,7 @@ Tiers: `free` ### `usage_activity_by_stage.secure.user_dependency_scanning_jobs` -no idea, Count of Dependency Scanning jobs run, it implies user but AFAIK we don't track per user +Total number of users running Dependency Scanning jobs [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175216_user_dependency_scanning_jobs.yml) @@ -17188,9 +17428,9 @@ Tiers: `ultimate` ### `usage_activity_by_stage.secure.user_license_management_jobs` -no idea, Count of License Scanning jobs run, it implies user but AFAIK we don't track per user +Total number of users running License Scanning jobs -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210216175218_user_license_management_jobs.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175218_user_license_management_jobs.yml) Group: `group::composition analysis` @@ -17200,7 +17440,7 @@ Tiers: `ultimate` ### `usage_activity_by_stage.secure.user_preferences_group_overview_security_dashboard` -Users who set personal preference to see Details on Group overview page +Users who set personal preference to see Details on Group information page [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182207_user_preferences_group_overview_security_dashboard.yml) @@ -17252,7 +17492,7 @@ Unique count of builds in project [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175525_ci_builds.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -17264,7 +17504,7 @@ Total pipelines in external repositories [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175527_ci_external_pipelines.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -17276,7 +17516,7 @@ Total pipelines in GitLab repositories [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175529_ci_internal_pipelines.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -17300,7 +17540,7 @@ Total Pipelines from templates in repository [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175533_ci_pipeline_config_repository.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -17312,7 +17552,7 @@ Pipeline schedules in GitLab [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175535_ci_pipeline_schedules.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -17324,7 +17564,7 @@ Distinct Users triggering Total pipelines [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175537_ci_pipelines.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -17336,7 +17576,7 @@ Total configured Triggers in project [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175539_ci_triggers.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -17360,7 +17600,7 @@ Projects with a GitHub service pipeline enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175540_projects_reporting_ci_cd_back_to_github.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -17590,21 +17830,21 @@ Projects with Prometheus alerting enabled Group: `group::monitor` -Status: `data_available` +Status: `removed` Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_design_management` -Missing description +Monthly active users for design management [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180745_action_monthly_active_users_design_management.yml) -Group: `group::knowledge` +Group: `group::product planning` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_git_write` @@ -17620,7 +17860,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_ide_edit` -Count unique edit actions when users used an IDE, no matter which one +Number of unique users per month who edited a file from any web editor [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180327_action_monthly_active_users_ide_edit.yml) @@ -17628,7 +17868,7 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_project_repo` @@ -17644,7 +17884,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_sfe_edit` -Count unique edit actions using the single file editor +Number of users using single file editor [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180321_action_monthly_active_users_sfe_edit.yml) @@ -17652,11 +17892,11 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_snippet_editor_edit` -Count unique edit actions using the snippet editor +Number of users using the snippet editor [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180323_action_monthly_active_users_snippet_editor_edit.yml) @@ -17664,11 +17904,11 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_sse_edit` -Count unique edit actions using the static site editor +Number of users using the static site editor [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180325_action_monthly_active_users_sse_edit.yml) @@ -17676,11 +17916,11 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_web_ide_edit` -Count unique edit actions using the web IDE +Number of users editing using web IDE [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180319_action_monthly_active_users_web_ide_edit.yml) @@ -17688,19 +17928,19 @@ Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_wiki_repo` -Missing description +Unique monthly active users of the Wiki [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180747_action_monthly_active_users_wiki_repo.yml) -Group: `group::knowledge` +Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.approval_project_rules` @@ -17956,7 +18196,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.snippets` -Monthly Snippets +Count of distinct author_id from snippets for last 28 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180317_snippets.yml) @@ -18034,7 +18274,7 @@ Missing description Group: `` -Status: `implemented` +Status: `data_available` Tiers: `free`, `premium`, `ultimate` @@ -18062,6 +18302,18 @@ Status: `data_available` Tiers: `free` +### `usage_activity_by_stage_monthly.manage.custom_compliance_frameworks` + +Monthly count of all custom compliance framework labels + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210507165054_custom_compliance_frameworks.yml) + +Group: `compliance` + +Status: `data_available` + +Tiers: `premium`, `ultimate` + ### `usage_activity_by_stage_monthly.manage.events` Missing description @@ -18088,39 +18340,39 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.manage.group_imports.group_import` -Missing description +Number of group import states [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183709_group_import.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.group_saml_enabled` -Missing description +Whether group SAML is enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/settings/20210216180833_group_saml_enabled.yml) -Group: `group::manage` +Group: `group:access` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.groups` -Missing description +Number of users who are group members for last 28 days [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180816_groups.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.groups_imported` @@ -18128,7 +18380,7 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183737_groups_imported.yml) -Group: `` +Group: `group::import` Status: `deprecated` @@ -18232,43 +18484,43 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.manage.ldap_admin_sync_enabled` -Missing description +Whether LDAP admin sync is enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/settings/20210216180831_ldap_admin_sync_enabled.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.ldap_group_sync_enabled` -Missing description +Has the instance configured [LDAP Group Sync](https://docs.gitlab.com/ee/administration/auth/ldap/#group-sync) [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/settings/20210216180829_ldap_group_sync_enabled.yml) -Group: `group::manage` +Group: `group::acess` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.ldap_keys` -Missing description +Number of users creating keys synced as part of LDAP for last 28 days. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180820_ldap_keys.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216180820_ldap_keys.yml) -Group: `group::manage` +Group: `group::acess` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.ldap_servers` -Missing description +Number of LDAP servers configured [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216180827_ldap_servers.yml) @@ -18276,103 +18528,103 @@ Group: `group::manage` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.ldap_users` -Missing description +Number of users that are linked to LDAP -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180822_ldap_users.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216180822_ldap_users.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.omniauth_providers` -Missing description +Number of unique user logins using an OmniAuth provider [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183627_omniauth_providers.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.project_imports.bitbucket` -Missing description +Count of projects imported from Bitbucket [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183650_bitbucket.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.project_imports.bitbucket_server` -Missing description +Count of projects imported from Bitbucket Server [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183652_bitbucket_server.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.project_imports.git` -Missing description +Count of projects imported from Git [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183655_git.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.project_imports.gitea` -Missing description +Count of projects imported from Gitea [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183653_gitea.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.project_imports.github` -Missing description +Count of projects imported from GitHub [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183648_github.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.project_imports.gitlab` -Missing description +Count of projects imported from GitLab using Project Export/Import [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183646_gitlab.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.project_imports.gitlab_migration` @@ -18380,11 +18632,11 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183659_gitlab_migration.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.project_imports.gitlab_project` @@ -18392,11 +18644,11 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183644_gitlab_project.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.project_imports.manifest` @@ -18404,35 +18656,47 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183657_manifest.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` + +### `usage_activity_by_stage_monthly.manage.project_imports.total` + +Total count of projects imported + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210520111133_total.yml) + +Group: `group::import` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.projects_imported.bitbucket` -Missing description +Count of projects imported from Bitbucket [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183720_bitbucket.yml) -Group: `` +Group: `group::import` Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.projects_imported.bitbucket_server` -Missing description +Count of projects imported from Bitbucket Server [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183722_bitbucket_server.yml) -Group: `` +Group: `group::import` Status: `deprecated` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.projects_imported.git` @@ -18532,75 +18796,75 @@ Tiers: ### `usage_activity_by_stage_monthly.manage.unique_users_all_imports` -Missing description +Number of users from projects imported [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183638_unique_users_all_imports.yml) -Group: `` +Group: `group::import` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.user_auth_by_provider.google_oauth2` -Missing description +Number of unique user logins using Google OAuth authentication [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183636_google_oauth2.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.user_auth_by_provider.standard` -Missing description +Number of unique user logins using password authentication [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183634_standard.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.user_auth_by_provider.two-factor` -Missing description +Number of unique user logins using two factor authentication [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183629_two-factor.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.user_auth_by_provider.two-factor-via-u2f-device` -Missing description +Number of unique user logins using two factor via a U2F device [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183631_two-factor-via-u2f-device.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.user_auth_by_provider.two-factor-via-webauthn-device` -Missing description +Number of unique user logins using two factor via a WebAuthn device [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183633_two-factor-via-webauthn-device.yml) -Group: `` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.users_created` @@ -18608,11 +18872,11 @@ Number of users created in the month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180818_users_created.yml) -Group: `group::manage` +Group: `group::access` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.value_stream_management_customized_group_stages` @@ -18736,7 +19000,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.package.projects_with_packages` -Incident confidential status changed event +The total number of projects in a given month with at least one package [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216181057_projects_with_packages.yml) @@ -18744,7 +19008,7 @@ Group: `group::package` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.plan.assignee_lists` @@ -18932,7 +19196,7 @@ Count creator_id from projects with repository mirroring enabled. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216181943_projects_mirrored_with_pipelines_enabled.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -19060,7 +19324,7 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.secure.dependency_scanning_pipeline` -no idea, what is this when did it get added? guess pipelines containing a DS job +Count of pipelines with successful Dependency Scanning jobs [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175226_dependency_scanning_pipeline.yml) @@ -19072,15 +19336,15 @@ Tiers: `ultimate` ### `usage_activity_by_stage_monthly.secure.dependency_scanning_scans` -Missing description +Monthly number of users running Dependency Scanning Scans -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183828_dependency_scanning_scans.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216183828_dependency_scanning_scans.yml) -Group: `` +Group: `group::composition analysis` Status: `data_available` -Tiers: `free` +Tiers: `ultimate` ### `usage_activity_by_stage_monthly.secure.sast_pipeline` @@ -19192,7 +19456,7 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.secure.user_dependency_scanning_jobs` -no idea, Count of Dependency Scanning jobs run, it implies user and monthly, but AFAIK we don't track per user +Monthly number of users creating Dependency Scanning jobs [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175222_user_dependency_scanning_jobs.yml) @@ -19204,9 +19468,9 @@ Tiers: `ultimate` ### `usage_activity_by_stage_monthly.secure.user_license_management_jobs` -no idea, Count of License Scanning jobs run, it implies user and monthly, but AFAIK we don't track per user +Monthly number of users running License Scanning jobs -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/license/20210216175224_user_license_management_jobs.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175224_user_license_management_jobs.yml) Group: `group::composition analysis` @@ -19216,7 +19480,7 @@ Tiers: `ultimate` ### `usage_activity_by_stage_monthly.secure.user_preferences_group_overview_security_dashboard` -Users who set personal preference to see Security Dashboard on Group overview page +Users who set personal preference to see Security Dashboard on Group information page [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216182209_user_preferences_group_overview_security_dashboard.yml) @@ -19268,7 +19532,7 @@ Unique monthly builds in project [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175542_ci_builds.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -19280,7 +19544,7 @@ Total pipelines in external repositories in a month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175544_ci_external_pipelines.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -19292,7 +19556,7 @@ Total pipelines in GitLab repositories in a month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175546_ci_internal_pipelines.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -19316,7 +19580,7 @@ Total Monthly Pipelines from templates in repository [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175550_ci_pipeline_config_repository.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -19328,7 +19592,7 @@ Total monthly Pipeline schedules in GitLab [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175552_ci_pipeline_schedules.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -19340,7 +19604,7 @@ Distinct users triggering pipelines in a month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175554_ci_pipelines.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -19352,7 +19616,7 @@ Total configured Triggers in project [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175556_ci_triggers.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -19376,7 +19640,7 @@ Projects with a GitHub repository mirror pipeline enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175558_projects_reporting_ci_cd_back_to_github.yml) -Group: `group::continuous integration` +Group: `group::pipeline execution` Status: `data_available` @@ -19408,12 +19672,12 @@ Tiers: `free`, `premium`, `ultimate` ### `web_ide_clientside_preview_enabled` -Whether web ide clientside preview is enabled +Whether Web IDE clientside preview is enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210204124920_web_ide_clientside_preview_enabled.yml) -Group: `group::product intelligence` +Group: `group::editor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` diff --git a/doc/development/usage_ping/index.md b/doc/development/usage_ping/index.md index 292e1256cb8..95dc4f2979a 100644 --- a/doc/development/usage_ping/index.md +++ b/doc/development/usage_ping/index.md @@ -50,10 +50,10 @@ More links: You can view the exact JSON payload sent to GitLab Inc. in the administration panel. To view the payload: 1. Sign in as a user with [Administrator](../../user/permissions.md) permissions. -1. In the top navigation bar, click **(admin)** **Admin Area**. -1. In the left sidebar, go to **Settings > Metrics and profiling**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. -1. Click the **Preview payload** button. +1. Select **Preview payload**. For an example payload, see [Example Usage Ping payload](#example-usage-ping-payload). @@ -62,10 +62,10 @@ For an example payload, see [Example Usage Ping payload](#example-usage-ping-pay To disable Usage Ping in the GitLab UI: 1. Sign in as a user with [Administrator](../../user/permissions.md) permissions. -1. In the top navigation bar, click **(admin)** **Admin Area**. -1. In the left sidebar, go to **Settings > Metrics and profiling**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. -1. Clear the **Usage Ping** checkbox and click **Save changes**. +1. Clear the **Enable usage ping** checkbox and select **Save changes**. To disable Usage Ping and prevent it from being configured in the future through the administration panel, Omnibus installs can set the following in @@ -1014,7 +1014,7 @@ Check if new metrics need to be added to the Versions Application. See `usage_da Add the `feature` label to the Merge Request for new Usage Ping metrics. These are user-facing changes and are part of expanding the Usage Ping feature. -### 8. Add a changelog file +### 8. Add a changelog Ensure you comply with the [Changelog entries guide](../changelog.md). @@ -1354,7 +1354,6 @@ The following is example content of the Usage Ping payload. "reply_by_email_enabled": "incoming+%{key}@incoming.gitlab.com", "signup_enabled": true, "web_ide_clientside_preview_enabled": true, - "ingress_modsecurity_enabled": true, "projects_with_expiration_policy_disabled": 999, "projects_with_expiration_policy_enabled": 999, ... diff --git a/doc/development/usage_ping/metrics_dictionary.md b/doc/development/usage_ping/metrics_dictionary.md index 40beee3c408..6b5fed4bcca 100644 --- a/doc/development/usage_ping/metrics_dictionary.md +++ b/doc/development/usage_ping/metrics_dictionary.md @@ -34,16 +34,18 @@ Each metric is defined in a separate YAML file consisting of a number of fields: | `product_group` | yes | The [group](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) that owns the metric. | | `product_category` | no | The [product category](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml) for the metric. | | `value_type` | yes | `string`; one of [`string`, `number`, `boolean`, `object`](https://json-schema.org/understanding-json-schema/reference/type.html). | -| `status` | yes | `string`; [status](#metric-statuses) of the metric, may be set to `data_available`, `implemented`, `not_used`, `deprecated`, `removed`. | +| `status` | yes | `string`; [status](#metric-statuses) of the metric, may be set to `data_available`, `implemented`, `not_used`, `deprecated`, `removed`, `broken`. | | `time_frame` | yes | `string`; may be set to a value like `7d`, `28d`, `all`, `none`. | | `data_source` | yes | `string`; may be set to a value like `database`, `redis`, `redis_hll`, `prometheus`, `system`. | +| `data_category` | yes | `string`; [categories](#data-category) of the metric, may be set to `Operational`, `Optional`, `Subscription`, `Standard`. | | `instrumentation_class` | no | `string`; [the class that implements the metric](metrics_instrumentation.md). | | `distribution` | yes | `array`; may be set to one of `ce, ee` or `ee`. The [distribution](https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/#definitions) where the tracked feature is available. | | `tier` | yes | `array`; may be set to one of `free, premium, ultimate`, `premium, ultimate` or `ultimate`. The [tier]( https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the tracked feature is available. | | `milestone` | no | The milestone when the metric is introduced. | | `milestone_removed` | no | The milestone when the metric is removed. | | `introduced_by_url` | no | The URL to the Merge Request that introduced the metric. | -| `extra` | no | `object`: extra information needed to calculate the metric value. | +| `repair_issue_url` | no | The URL of the issue that was created to repair a metric with a `broken` status. | +| `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 statuses @@ -53,10 +55,30 @@ Metric definitions can have one of the following statuses: - `data_available`: Metric data is available and used in a Sisense dashboard. - `implemented`: Metric is implemented but data is not yet available. This is a temporary status for newly added metrics awaiting inclusion in a new release. +- `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. - `not_used`: Metric is not used in any dashboard. - `deprecated`: Metric is deprecated and possibly planned to be removed. - `removed`: Metric was removed, but it may appear in Usage Ping payloads sent from instances running on older versions of GitLab. +### Metric value_type + +Metric definitions can have one of the following values for `value_type`: + +- `boolean` +- `number` +- `string` +- `object`: A metric with `value_type: object` must have `value_json_schema` with a link to the JSON schema for the object. +In general, we avoid complex objects and prefer one of the `boolean`, `number`, or `string` value types. +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 + +- `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`. +- `all`: The metric data applies for the whole time the metric has been active (all-time interval). For example, the following metric counts all users that create issues: `/config/metrics/counts_all/20210216181115_issues.yml`. +- `none`: The metric collects a type of data that's not tracked over time, such as settings and configuration information. Therefore, a time interval is not applicable. For example, `uuid` has no time interval applicable: `config/metrics/license/20210201124933_uuid.yml`. + ### Metric name To improve metric discoverability by a wider audience, each metric with @@ -72,6 +94,15 @@ Metric name suggestions can contain two types of elements: For a metric name to be valid, it must not include any prompt, and no fixed suggestions should be changed. +### Data category + +We use the following categories to classify a metric: + +- `Operational`: Required data for operational purposes. +- `Optional`: Data that is optional to collect. This can be [enabled or disabled](../usage_ping/index.md#disable-usage-ping) in the Admin Area. +- `Subscription`: Data related to licensing. +- `Standard`: Standard set of identifiers that are included when collecting data. + ### Metric name suggestion examples #### Metric with `data_source: database` diff --git a/doc/development/usage_ping/metrics_instrumentation.md b/doc/development/usage_ping/metrics_instrumentation.md index 2cb24fab6cc..ff0dbf99a09 100644 --- a/doc/development/usage_ping/metrics_instrumentation.md +++ b/doc/development/usage_ping/metrics_instrumentation.md @@ -26,7 +26,7 @@ A metric definition has the [`instrumentation_class`](metrics_dictionary.md) fie The defined instrumentation class should have one of the existing metric classes: `DatabaseMetric`, `RedisHLLMetric`, or `GenericMetric`. -Using the instrumentation classes ensures that metrics can fail safe individually, without breaking the entire +Using the instrumentation classes ensures that metrics can fail safe individually, without breaking the entire process of Usage Ping generation. We have built a domain-specific language (DSL) to define the metrics instrumentation. @@ -53,20 +53,17 @@ end ## Redis HyperLogLog metrics -[Example of a merge request that adds a `RedisHLL` metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60089/diffs). +[Example of a merge request that adds a `RedisHLL` metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61685). -```ruby -module Gitlab - module Usage - module Metrics - module Instrumentations - class CountUsersUsingApproveQuickActionMetric < RedisHLLMetric - event_names :i_quickactions_approve - end - end - end - end -end +Count unique values for `i_quickactions_approve` event. + +```yaml +time_frame: 28d +data_source: redis_hll +instrumentation_class: 'Gitlab::Usage::Metrics::Instrumentations::RedisHLLMetric' +options: + events: + - i_quickactions_approve ``` ## Generic metrics @@ -88,3 +85,18 @@ module Gitlab end end ``` + +## Creating a new metric instrumentation class + +To create a stub instrumentation for a Usage Ping metric, you can use a dedicated [generator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/gitlab/usage_metric_generator.rb): + +The generator takes the class name as an argument and the following options: + +- `--type=TYPE` Required. Indicates the metric type. It must be one of: `database`, `generic`, `redis_hll`. +- `--ee` Indicates if the metric is for EE. + +```shell +rails generate gitlab:usage_metric CountIssues --type database + create lib/gitlab/usage/metrics/instrumentations/count_issues_metric.rb + create spec/lib/gitlab/usage/metrics/instrumentations/count_issues_metric_spec.rb +``` diff --git a/doc/development/utilities.md b/doc/development/utilities.md index d7baa6b23a5..b9b4c6448e2 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -10,11 +10,11 @@ We have developed a number of utilities to help ease development: ## `MergeHash` -Refer to [`merge_hash.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/utils/merge_hash.rb): +Refer to [`merge_hash.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/utils/merge_hash.rb): - Deep merges an array of hashes: - ``` ruby + ```ruby Gitlab::Utils::MergeHash.merge( [{ hello: ["world"] }, { hello: "Everyone" }, @@ -25,7 +25,7 @@ Refer to [`merge_hash.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/ Gives: - ``` ruby + ```ruby [ { hello: @@ -41,7 +41,7 @@ Refer to [`merge_hash.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/ - Extracts all keys and values from a hash into an array: - ``` ruby + ```ruby Gitlab::Utils::MergeHash.crush( { hello: "world", this: { crushes: ["an entire", "hash"] } } ) @@ -49,13 +49,13 @@ Refer to [`merge_hash.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/ Gives: - ``` ruby + ```ruby [:hello, "world", :this, :crushes, "an entire", "hash"] ``` ## `Override` -Refer to [`override.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/utils/override.rb): +Refer to [`override.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/utils/override.rb): - This utility can help you check if one method would override another or not. It is the same concept as Java's `@Override` annotation @@ -69,7 +69,7 @@ Refer to [`override.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gi Here's a simple example: - ``` ruby + ```ruby class Base def execute end @@ -86,7 +86,7 @@ Refer to [`override.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gi This also works on modules: - ``` ruby + ```ruby module Extension extend ::Gitlab::Utils::Override @@ -152,7 +152,7 @@ Derived.f # => nil ## `StrongMemoize` -Refer to [`strong_memoize.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/utils/strong_memoize.rb): +Refer to [`strong_memoize.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/utils/strong_memoize.rb): - Memoize the value even if it is `nil` or `false`. @@ -164,7 +164,7 @@ Refer to [`strong_memoize.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/ Instead of writing patterns like this: - ``` ruby + ```ruby class Find def result return @result if defined?(@result) @@ -176,7 +176,7 @@ Refer to [`strong_memoize.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/ You could write it like: - ``` ruby + ```ruby class Find include Gitlab::Utils::StrongMemoize @@ -190,7 +190,7 @@ Refer to [`strong_memoize.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/ - Clear memoization - ``` ruby + ```ruby class Find include Gitlab::Utils::StrongMemoize end @@ -200,7 +200,7 @@ Refer to [`strong_memoize.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/ ## `RequestCache` -Refer to [`request_cache.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/cache/request_cache.rb). +Refer to [`request_cache.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/cache/request_cache.rb). This module provides a simple way to cache values in RequestStore, and the cache key would be based on the class name, method name, @@ -209,7 +209,7 @@ method level values, and optional method arguments. A simple example that only uses the instance level customised values is: -``` ruby +```ruby class UserAccess extend Gitlab::Cache::RequestCache @@ -230,7 +230,7 @@ instance variable so the cache logic would be the same. We can also set different strategies for different methods: -``` ruby +```ruby class Commit extend Gitlab::Cache::RequestCache diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index 7d20382973a..abf49d31de2 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -1,5 +1,6 @@ --- redirect_to: 'avoiding_downtime_in_migrations.md' +remove_date: '2021-07-01' --- This document was moved to [another location](avoiding_downtime_in_migrations.md). diff --git a/doc/development/wikis.md b/doc/development/wikis.md index 9998e29b596..994312da98e 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -40,7 +40,7 @@ Some notable gems that are used for wikis are: We only use Gollum as a storage abstraction layer, to handle the mapping between wiki page slugs and files in the repository. When rendering wiki pages, we don't use Gollum at all and instead go through a -[custom Banzai pipeline](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/pipeline/wiki_pipeline.rb). +[custom Banzai pipeline](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/pipeline/wiki_pipeline.rb). This adds some [wiki-specific markup](../user/markdown.md#wiki-specific-markdown), such as Gollum's `[[link]]` syntax. Because we do not make use of most of Gollum's features, we plan to move away from it entirely at some point. |
