From b0be58a1b313df976ea4b0e37163f8fea81ce5f4 Mon Sep 17 00:00:00 2001 From: Brett Walker Date: Thu, 6 Sep 2018 16:52:18 +0000 Subject: Resolve "CE documentation is not CommonMark compliant" --- CONTRIBUTING.md | 2 +- doc/administration/auth/ldap.md | 35 +- doc/administration/container_registry.md | 24 +- doc/administration/custom_hooks.md | 3 +- doc/administration/gitaly/index.md | 3 +- doc/administration/high_availability/README.md | 2 +- doc/administration/high_availability/gitlab.md | 2 +- doc/administration/high_availability/redis.md | 61 +- doc/administration/index.md | 6 +- doc/administration/integration/koding.md | 21 +- doc/administration/integration/plantuml.md | 11 +- doc/administration/integration/terminal.md | 3 +- doc/administration/job_artifacts.md | 47 +- doc/administration/job_traces.md | 46 +- doc/administration/monitoring/prometheus/index.md | 18 +- doc/administration/pages/index.md | 86 +-- doc/administration/pages/source.md | 148 ++--- doc/administration/repository_storage_paths.md | 48 +- doc/administration/troubleshooting/sidekiq.md | 16 +- doc/administration/uploads.md | 105 ++-- doc/api/jobs.md | 6 +- doc/api/services.md | 8 +- doc/api/v3_to_v4.md | 4 +- doc/ci/docker/using_docker_build.md | 15 +- doc/ci/docker/using_docker_images.md | 71 +-- doc/ci/environments.md | 53 +- .../test_phoenix_app_with_gitlab_ci_cd/index.md | 4 +- doc/ci/git_submodules.md | 19 +- doc/ci/review_apps/index.md | 9 +- doc/ci/runners/README.md | 5 +- doc/ci/ssh_keys/README.md | 4 +- doc/ci/triggers/README.md | 29 +- doc/ci/yaml/README.md | 93 +-- doc/development/automatic_ce_ee_merge.md | 36 +- doc/development/background_migrations.md | 40 +- doc/development/code_review.md | 98 +-- doc/development/contributing/index.md | 2 +- doc/development/contributing/issue_workflow.md | 4 +- .../contributing/merge_request_workflow.md | 32 +- doc/development/diffs.md | 10 +- doc/development/documentation/styleguide.md | 8 +- doc/development/ee_features.md | 94 +-- doc/development/fe_guide/performance.md | 3 +- doc/development/fe_guide/style_guide_js.md | 698 +++++++++++---------- doc/development/fe_guide/vuex.md | 33 +- doc/development/gotchas.md | 6 +- doc/development/i18n/proofreader.md | 1 - .../new_fe_guide/development/testing.md | 2 +- doc/development/new_fe_guide/style/javascript.md | 213 ++++--- doc/development/newlines_styleguide.md | 4 +- doc/development/sidekiq_debugging.md | 3 +- doc/development/testing_guide/ci.md | 30 +- doc/development/testing_guide/testing_levels.md | 2 +- doc/gitlab-basics/create-project.md | 6 +- doc/install/azure/index.md | 30 +- doc/install/database_mysql.md | 18 +- doc/install/kubernetes/gitlab_chart.md | 6 +- doc/install/openshift_and_gitlab/index.md | 101 +-- doc/integration/azure.md | 2 +- doc/integration/oauth2_generic.md | 26 +- doc/integration/omniauth.md | 38 +- doc/integration/saml.md | 7 +- .../numerous_undo_possibilities_in_git/index.md | 138 ++-- doc/university/README.md | 8 +- doc/university/high-availability/aws/README.md | 4 +- doc/university/support/README.md | 42 +- doc/university/training/topics/bisect.md | 2 +- doc/university/training/topics/env_setup.md | 4 +- doc/university/training/topics/getting_started.md | 25 +- doc/university/training/topics/git_add.md | 38 +- doc/university/training/topics/git_log.md | 35 +- doc/university/training/topics/rollback_commits.md | 28 +- doc/university/training/topics/stash.md | 58 +- doc/university/training/topics/unstage.md | 27 +- doc/update/8.17-to-9.0.md | 74 +-- doc/update/9.0-to-9.1.md | 76 +-- doc/user/admin_area/monitoring/health_check.md | 14 +- doc/user/award_emojis.md | 10 +- doc/user/discussions/index.md | 6 +- doc/user/group/index.md | 16 +- doc/user/group/subgroups/index.md | 24 +- doc/user/markdown.md | 10 +- .../profile/account/two_factor_authentication.md | 8 +- doc/user/project/bulk_editing.md | 11 +- doc/user/project/clusters/eks_and_gitlab/index.md | 6 +- doc/user/project/clusters/index.md | 20 +- doc/user/project/container_registry.md | 32 +- doc/user/project/cycle_analytics.md | 2 +- doc/user/project/integrations/bamboo.md | 4 +- doc/user/project/integrations/jira.md | 28 +- doc/user/project/integrations/webhooks.md | 38 +- doc/user/project/issue_board.md | 24 +- doc/user/project/koding.md | 8 +- doc/user/project/merge_requests/versions.md | 14 +- doc/user/project/new_ci_build_permissions_model.md | 20 +- doc/user/project/pages/index.md | 16 +- doc/user/project/pipelines/job_artifacts.md | 40 +- doc/user/project/pipelines/schedules.md | 10 +- doc/user/project/protected_branches.md | 2 +- doc/user/project/protected_tags.md | 2 +- .../project/repository/gpg_signed_commits/index.md | 19 +- .../repository/reducing_the_repo_size_using_git.md | 17 +- doc/user/reserved_names.md | 6 +- .../lfs/manage_large_binaries_with_git_lfs.md | 11 +- doc/workflow/notifications.md | 6 +- 105 files changed, 1809 insertions(+), 1734 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b9e9d4a5a3..7f1da58fa9d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ _This notice should stay as the first item in the CONTRIBUTING.md file._ - [Release Scoping labels](#release-scoping-labels) - [Priority labels](#priority-labels) - [Severity labels](#severity-labels) - - [Severity impact guidance](#severity-impact-guidance) + - [Severity impact guidance](#severity-impact-guidance) - [Label for community contributors](#label-for-community-contributors) - [Implement design & UI elements](#implement-design--ui-elements) - [Issue tracker](#issue-tracker) diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index 3c98d683924..5c7392b99d0 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -382,29 +382,30 @@ the configuration option `lowercase_usernames`. By default, this configuration o 1. Edit `/etc/gitlab/gitlab.rb`: - ```ruby - gitlab_rails['ldap_servers'] = YAML.load <<-EOS - main: - # snip... - lowercase_usernames: true - EOS - ``` + ```ruby + gitlab_rails['ldap_servers'] = YAML.load <<-EOS + main: + # snip... + lowercase_usernames: true + EOS + ``` -2. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. **Source configuration** 1. Edit `config/gitlab.yaml`: - ```yaml - production: - ldap: - servers: - main: - # snip... - lowercase_usernames: true - ``` -2. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. + ```yaml + production: + ldap: + servers: + main: + # snip... + lowercase_usernames: true + ``` + +1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. ## Encryption diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index 2441ff85783..890b780fe80 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -1,11 +1,11 @@ # GitLab Container Registry administration > **Notes:** -- [Introduced][ce-4040] in GitLab 8.8. -- Container Registry manifest `v1` support was added in GitLab 8.9 to support - Docker versions earlier than 1.10. -- This document is about the admin guide. To learn how to use GitLab Container - Registry [user documentation](../user/project/container_registry.md). +> - [Introduced][ce-4040] in GitLab 8.8. +> - Container Registry manifest `v1` support was added in GitLab 8.9 to support +> Docker versions earlier than 1.10. +> - This document is about the admin guide. To learn how to use GitLab Container +> Registry [user documentation](../user/project/container_registry.md). With the Container Registry integrated into GitLab, every project can have its own space to store its Docker images. @@ -203,10 +203,10 @@ If you have a [wildcard certificate][], you need to specify the path to the certificate in addition to the URL, in this case `/etc/gitlab/gitlab.rb` will look like: > -```ruby -registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem" -registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" -``` +> ```ruby +> registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem" +> registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" +> ``` --- @@ -375,7 +375,7 @@ Read more about the individual driver's config options in the > **Warning** GitLab will not backup Docker images that are not stored on the filesystem. Remember to enable backups with your object storage provider if desired. - +> > **Important** Enabling storage driver other than `filesystem` would mean that your Docker client needs to be able to access the storage backend directly. So you must use an address that resolves and is accessible outside GitLab server. @@ -598,11 +598,11 @@ thus the error above. While GitLab doesn't support using self-signed certificates with Container Registry out of the box, it is possible to make it work if you follow -[Docker's documentation][docker-insecure]. You may find some additional +[Docker's documentation][docker-insecure-self-signed]. You may find some additional information in [issue 18239][ce-18239]. [ce-18239]: https://gitlab.com/gitlab-org/gitlab-ce/issues/18239 -[docker-insecure]: https://docs.docker.com/registry/insecure/#using-self-signed-certificates +[docker-insecure-self-signed]: https://docs.docker.com/registry/insecure/#use-self-signed-certificates [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure [restart gitlab]: restart_gitlab.md#installations-from-source [wildcard certificate]: https://en.wikipedia.org/wiki/Wildcard_certificate diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md index 1c508c77ffa..9b0fabb9259 100644 --- a/doc/administration/custom_hooks.md +++ b/doc/administration/custom_hooks.md @@ -1,7 +1,6 @@ # Custom Git Hooks -> -**Note:** Custom Git hooks must be configured on the filesystem of the GitLab +> **Note:** Custom Git hooks must be configured on the filesystem of the GitLab server. Only GitLab server administrators will be able to complete these tasks. Please explore [webhooks] and [CI] as an option if you do not have filesystem access. For a user configurable Git hook interface, see diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 36567173125..964758837e5 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -101,8 +101,7 @@ documentation on configuring Gitaly authentication](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md#authentication) . -> -**NOTE:** In most or all cases the storage paths below end in `/repositories` which is +> **NOTE:** In most or all cases the storage paths below end in `/repositories` which is different than `path` in `git_data_dirs` of Omnibus installations. Check the directory layout on your Gitaly server to be sure. diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md index ea8077f0623..49fe80fb2a6 100644 --- a/doc/administration/high_availability/README.md +++ b/doc/administration/high_availability/README.md @@ -37,7 +37,7 @@ Follow the steps below to configure an active/active setup: 1. [Configure the database](database.md) 1. [Configure Redis](redis.md) - 1. [Configure Redis for GitLab source installations](redis_source.md) + 1. [Configure Redis for GitLab source installations](redis_source.md) 1. [Configure NFS](nfs.md) 1. [Configure the GitLab application servers](gitlab.md) 1. [Configure the load balancers](load_balancer.md) diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index b74554a5598..f16ae835ced 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -84,7 +84,7 @@ for each GitLab application server in your environment. servers should point to the external url that users will use to access GitLab. In a typical HA setup, this will be the url of the load balancer which will route traffic to all GitLab application servers in the HA cluster. - + > > **Note:** When you specify `https` in the `external_url`, as in the example above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If certificates are not present, Nginx will fail to start. See diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index 031fb31ca4f..e05bebbef18 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -1,7 +1,6 @@ # Configuring Redis for GitLab HA -> -Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11. +> Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11. Starting with 8.14, Redis Sentinel is no longer experimental. If you've used it with versions `< 8.14` before, please check the updated documentation here. @@ -15,20 +14,20 @@ a hosted cloud solution or you can use the one that comes bundled with Omnibus GitLab packages. > **Notes:** -- Redis requires authentication for High Availability. See - [Redis Security](http://redis.io/topics/security) documentation for more - information. We recommend using a combination of a Redis password and tight - firewall rules to secure your Redis service. -- You are highly encouraged to read the [Redis Sentinel][sentinel] documentation - before configuring Redis HA with GitLab to fully understand the topology and - architecture. -- This is the documentation for the Omnibus GitLab packages. For installations - from source, follow the [Redis HA source installation](redis_source.md) guide. -- Redis Sentinel daemon is bundled with Omnibus GitLab Enterprise Edition only. - For configuring Sentinel with the Omnibus GitLab Community Edition and - installations from source, read the - [Available configuration setups](#available-configuration-setups) section - below. +> - Redis requires authentication for High Availability. See +> [Redis Security](http://redis.io/topics/security) documentation for more +> information. We recommend using a combination of a Redis password and tight +> firewall rules to secure your Redis service. +> - You are highly encouraged to read the [Redis Sentinel][sentinel] documentation +> before configuring Redis HA with GitLab to fully understand the topology and +> architecture. +> - This is the documentation for the Omnibus GitLab packages. For installations +> from source, follow the [Redis HA source installation](redis_source.md) guide. +> - Redis Sentinel daemon is bundled with Omnibus GitLab Enterprise Edition only. +> For configuring Sentinel with the Omnibus GitLab Community Edition and +> installations from source, read the +> [Available configuration setups](#available-configuration-setups) section +> below. ## Overview @@ -55,11 +54,11 @@ components below. ### High Availability with Sentinel ->**Notes:** -- Starting with GitLab `8.11`, you can configure a list of Redis Sentinel - servers that will monitor a group of Redis servers to provide failover support. -- Starting with GitLab `8.14`, the Omnibus GitLab Enterprise Edition package - comes with Redis Sentinel daemon built-in. +> **Notes:** +> - Starting with GitLab `8.11`, you can configure a list of Redis Sentinel +> servers that will monitor a group of Redis servers to provide failover support. +> - Starting with GitLab `8.14`, the Omnibus GitLab Enterprise Edition package +> comes with Redis Sentinel daemon built-in. High Availability with Redis requires a few things: @@ -231,13 +230,13 @@ Pick the one that suits your needs. This is the section where we install and setup the new Redis instances. ->**Notes:** -- We assume that you have installed GitLab and all HA components from scratch. If you - already have it installed and running, read how to - [switch from a single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha). -- Redis nodes (both master and slaves) will need the same password defined in - `redis['password']`. At any time during a failover the Sentinels can - reconfigure a node and change its status from master to slave and vice versa. +> **Notes:** +> - We assume that you have installed GitLab and all HA components from scratch. If you +> already have it installed and running, read how to +> [switch from a single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha). +> - Redis nodes (both master and slaves) will need the same password defined in +> `redis['password']`. At any time during a failover the Sentinels can +> reconfigure a node and change its status from master to slave and vice versa. ### Prerequisites @@ -383,9 +382,9 @@ multiple machines with the Sentinel daemon. [Download/install](https://about.gitlab.com/downloads-ee) the Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. + - Make sure you select the correct Omnibus package, with the same version + the GitLab application is running. + - Do not complete any other steps on the download page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents (if you are installing the Sentinels in the same node as the other Redis instances, some values might diff --git a/doc/administration/index.md b/doc/administration/index.md index 837a04f3e88..8b6a42b0ca5 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -135,15 +135,15 @@ created in snippets, wikis, and repos. - [Monitoring GitLab](monitoring/index.md): - [Monitoring uptime](../user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint. - - [IP whitelist](monitoring/ip_whitelist.md): Monitor endpoints that provide health check information when probed. - - [Monitoring GitHub imports](monitoring/github_imports.md): GitLab's GitHub Importer displays Prometheus metrics to monitor the health and progress of the importer. + - [IP whitelist](monitoring/ip_whitelist.md): Monitor endpoints that provide health check information when probed. + - [Monitoring GitHub imports](monitoring/github_imports.md): GitLab's GitHub Importer displays Prometheus metrics to monitor the health and progress of the importer. ### Performance Monitoring - [GitLab Performance Monitoring](monitoring/performance/index.md): - [Enable Performance Monitoring](monitoring/performance/gitlab_configuration.md): Enable GitLab Performance Monitoring. - [GitLab performance monitoring with InfluxDB](monitoring/performance/influxdb_configuration.md): Configure GitLab and InfluxDB for measuring performance metrics. - - [InfluxDB Schema](monitoring/performance/influxdb_schema.md): Measurements stored in InfluxDB. + - [InfluxDB Schema](monitoring/performance/influxdb_schema.md): Measurements stored in InfluxDB. - [GitLab performance monitoring with Prometheus](monitoring/prometheus/index.md): Configure GitLab and Prometheus for measuring performance metrics. - [GitLab performance monitoring with Grafana](monitoring/performance/grafana_configuration.md): Configure GitLab to visualize time series metrics through graphs and dashboards. - [Request Profiling](monitoring/performance/request_profiling.md): Get a detailed profile on slow requests. diff --git a/doc/administration/integration/koding.md b/doc/administration/integration/koding.md index 6c1ec3028cc..def0add0061 100644 --- a/doc/administration/integration/koding.md +++ b/doc/administration/integration/koding.md @@ -1,10 +1,10 @@ # Koding & GitLab ->**Notes:** -- **As of GitLab 10.0, the Koding integration is deprecated and will be removed - in a future version. The option to configure it is removed from GitLab's admin - area.** -- [Introduced][ce-5909] in GitLab 8.11. +> **Notes:** +> - **As of GitLab 10.0, the Koding integration is deprecated and will be removed +> in a future version. The option to configure it is removed from GitLab's admin +> area.** +> - [Introduced][ce-5909] in GitLab 8.11. This document will guide you through installing and configuring Koding with GitLab. @@ -117,12 +117,11 @@ requests. You need to enable Koding integration from Settings under Admin Area. To do that login with an Admin account and do followings; - - open [http://127.0.0.1:3000/admin/application_settings](http://127.0.0.1:3000/admin/application_settings) - - scroll to bottom of the page until Koding section - - check `Enable Koding` checkbox - - provide GitLab team page for running Koding instance as `Koding URL`* - -* For `Koding URL` you need to provide the gitlab integration enabled team on +- open [http://127.0.0.1:3000/admin/application_settings](http://127.0.0.1:3000/admin/application_settings) +- scroll to bottom of the page until Koding section +- check `Enable Koding` checkbox +- provide GitLab team page for running Koding instance as `Koding URL`* + * For `Koding URL` you need to provide the gitlab integration enabled team on your Koding installation. Team called `gitlab` has integration on Koding out of the box, so if you didn't change anything your team on Koding should be `gitlab`. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index d978d1dca53..293036f2f4b 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -74,28 +74,27 @@ our AsciiDoc snippets, wikis and repos using delimited blocks: ```plantuml Bob -> Alice : hello Alice -> Bob : Go Away - ``` - + ``` - **AsciiDoc** - 
+    ```
     [plantuml, format="png", id="myDiagram", width="200px"]
     --
     Bob->Alice : hello
     Alice -> Bob : Go Away
     --
-
+ ``` - **reStructuredText** - 
+    ```
     .. plantuml::
        :caption: Caption with **bold** and *italic*
 
        Bob -> Alice: hello
        Alice -> Bob: Go Away
-
+ ``` You can also use the `uml::` directive for compatibility with [sphinxcontrib-plantuml](https://pypi.python.org/pypi/sphinxcontrib-plantuml), but please note that we currently only support the `caption` option. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index e11ed58eb91..fa58d0ef15f 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,7 +1,6 @@ # Web terminals -> -[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7690) +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7690) in GitLab 8.15. Only project maintainers and owners can access web terminals. With the introduction of the [Kubernetes integration](../../user/project/clusters/index.md), diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 4b5be8699e9..1f3bc611cdf 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -87,13 +87,13 @@ _The artifacts are stored by default in ### Using object storage ->**Notes:** -- [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1762) in - [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. -- Since version 9.5, artifacts are [browsable](../user/project/pipelines/job_artifacts.md#browsing-artifacts), - when object storage is enabled. 9.4 lacks this feature. -- Since version 10.6, available in [GitLab Core](https://about.gitlab.com/pricing/) -- Since version 11.0, we support `direct_upload` to S3. +> **Notes:** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1762) in +> [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. +> - Since version 9.5, artifacts are [browsable](../user/project/pipelines/job_artifacts.md#browsing-artifacts), +> when object storage is enabled. 9.4 lacks this feature. +> - Since version 10.6, available in [GitLab Core](https://about.gitlab.com/pricing/) +> - Since version 11.0, we support `direct_upload` to S3. If you don't want to use the local disk where GitLab is installed to store the artifacts, you can use an object storage like AWS S3 instead. @@ -162,15 +162,15 @@ _The artifacts are stored by default in 1. Save the file and [reconfigure GitLab][] for the changes to take effect. 1. Migrate any existing local artifacts to the object storage: - ```bash - gitlab-rake gitlab:artifacts:migrate - ``` + ```bash + gitlab-rake gitlab:artifacts:migrate + ``` - Currently this has to be executed manually and it will allow you to - migrate the existing artifacts to the object storage, but all new - artifacts will still be stored on the local disk. In the future - you will be given an option to define a default storage artifacts for all - new files. + Currently this has to be executed manually and it will allow you to + migrate the existing artifacts to the object storage, but all new + artifacts will still be stored on the local disk. In the future + you will be given an option to define a default storage artifacts for all + new files. --- @@ -198,15 +198,15 @@ _The artifacts are stored by default in 1. Save the file and [restart GitLab][] for the changes to take effect. 1. Migrate any existing local artifacts to the object storage: - ```bash - sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production - ``` + ```bash + sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production + ``` - Currently this has to be executed manually and it will allow you to - migrate the existing artifacts to the object storage, but all new - artifacts will still be stored on the local disk. In the future - you will be given an option to define a default storage artifacts for all - new files. + Currently this has to be executed manually and it will allow you to + migrate the existing artifacts to the object storage, but all new + artifacts will still be stored on the local disk. In the future + you will be given an option to define a default storage artifacts for all + new files. ## Expiring artifacts @@ -266,6 +266,7 @@ you can flip the feature flag from a Rails console. ```ruby Feature.enable('ci_disable_validates_dependencies') ``` + --- **In installations from source:** diff --git a/doc/administration/job_traces.md b/doc/administration/job_traces.md index a792a5f2a97..63945506f3c 100644 --- a/doc/administration/job_traces.md +++ b/doc/administration/job_traces.md @@ -67,24 +67,24 @@ To archive those legacy job traces, please follow the instruction below. 1. Execute the following command - ```bash - gitlab-rake gitlab:traces:archive - ``` + ```bash + gitlab-rake gitlab:traces:archive + ``` - After you executed this task, GitLab instance queues up Sidekiq jobs (asynchronous processes) - for migrating job trace files from local storage to object storage. - It could take time to complete the all migration jobs. You can check the progress by the following command + After you executed this task, GitLab instance queues up Sidekiq jobs (asynchronous processes) + for migrating job trace files from local storage to object storage. + It could take time to complete the all migration jobs. You can check the progress by the following command - ```bash - sudo gitlab-rails console - ``` + ```bash + sudo gitlab-rails console + ``` - ```bash - [1] pry(main)> Sidekiq::Stats.new.queues['pipeline_background:archive_trace'] - => 100 - ``` + ```bash + [1] pry(main)> Sidekiq::Stats.new.queues['pipeline_background:archive_trace'] + => 100 + ``` - If the count becomes zero, the archiving processes are done + If the count becomes zero, the archiving processes are done ## How to migrate archived job traces to object storage @@ -95,9 +95,9 @@ If job traces have already been archived into local storage, and you want to mig 1. Ensure [Object storage integration for Job Artifacts](job_artifacts.md#object-storage-settings) is enabled 1. Execute the following command - ```bash - gitlab-rake gitlab:traces:migrate - ``` + ```bash + gitlab-rake gitlab:traces:migrate + ``` ## How to remove job traces @@ -185,15 +185,15 @@ with the legacy architecture. In some cases, having data stored on Redis could incur data loss: 1. **Case 1: When all data in Redis are accidentally flushed** - - On going live traces could be recovered by re-sending traces (this is - supported by all versions of the GitLab Runner). - - Finished jobs which have not archived live traces will lose the last part - (~128KB) of trace data. + - On going live traces could be recovered by re-sending traces (this is + supported by all versions of the GitLab Runner). + - Finished jobs which have not archived live traces will lose the last part + (~128KB) of trace data. 1. **Case 2: When Sidekiq workers fail to archive (e.g., there was a bug that prevents archiving process, Sidekiq inconsistency, etc.)** - - Currently all trace data in Redis will be deleted after one week. If the - Sidekiq workers can't finish by the expiry date, the part of trace data will be lost. + - Currently all trace data in Redis will be deleted after one week. If the + Sidekiq workers can't finish by the expiry date, the part of trace data will be lost. Another issue that might arise is that it could consume all memory on the Redis instance. If the number of jobs is 1000, 128MB (128KB * 1000) is consumed. diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 1c79e86dcb4..9d525645952 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -1,13 +1,13 @@ # GitLab Prometheus ->**Notes:** -- Prometheus and the various exporters listed in this page are bundled in the - Omnibus GitLab package. Check each exporter's documentation for the timeline - they got added. For installations from source you will have to install them - yourself. Over subsequent releases additional GitLab metrics will be captured. -- Prometheus services are on by default with GitLab 9.0. -- Prometheus and its exporters do not authenticate users, and will be available - to anyone who can access them. +> **Notes:** +> - Prometheus and the various exporters listed in this page are bundled in the +> Omnibus GitLab package. Check each exporter's documentation for the timeline +> they got added. For installations from source you will have to install them +> yourself. Over subsequent releases additional GitLab metrics will be captured. +> - Prometheus services are on by default with GitLab 9.0. +> - Prometheus and its exporters do not authenticate users, and will be available +> to anyone who can access them. [Prometheus] is a powerful time-series monitoring service, providing a flexible platform for monitoring GitLab and other software products. @@ -107,7 +107,7 @@ Sample Prometheus queries: > Introduced in GitLab 9.0. > Pod monitoring introduced in GitLab 9.4. -If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/operating/configuration/#) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them. +If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/operating/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them. To disable the monitoring of Kubernetes: diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index f16ba0b297d..3af0a5759a7 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -5,13 +5,13 @@ description: 'Learn how to administer GitLab Pages.' # GitLab Pages administration > **Notes:** -- [Introduced][ee-80] in GitLab EE 8.3. -- Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5. -- GitLab Pages [were ported][ce-14605] to Community Edition in GitLab 8.17. -- This guide is for Omnibus GitLab installations. If you have installed - GitLab from source, follow the [Pages source installation document](source.md). -- To learn how to use GitLab Pages, read the [user documentation][pages-userguide]. -- Does NOT support subgroups. See [this issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) for more information and status. +> - [Introduced][ee-80] in GitLab EE 8.3. +> - Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5. +> - GitLab Pages [were ported][ce-14605] to Community Edition in GitLab 8.17. +> - This guide is for Omnibus GitLab installations. If you have installed +> GitLab from source, follow the [Pages source installation document](source.md). +> - To learn how to use GitLab Pages, read the [user documentation][pages-userguide]. +> - Does NOT support subgroups. See [this issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) for more information and status. This document describes how to set up the _latest_ GitLab Pages feature. Make sure to read the [changelog](#changelog) if you are upgrading to a new GitLab @@ -107,12 +107,12 @@ since that is needed in all configurations. ### Wildcard domains ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) > ->--- +> --- > -URL scheme: `http://page.example.io` +> URL scheme: `http://page.example.io` This is the minimum setup that you can use Pages with. It is the base for all other setups as described below. Nginx will proxy all requests to the daemon. @@ -131,13 +131,13 @@ Watch the [video tutorial][video-admin] for this configuration. ### Wildcard domains with TLS support ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) +> - Wildcard TLS certificate > ->--- +> --- > -URL scheme: `https://page.example.io` +> URL scheme: `https://page.example.io` Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the outside world. @@ -168,13 +168,13 @@ you have IPv6 as well as IPv4 addresses, you can use them both. ### Custom domains ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Secondary IP +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) +> - Secondary IP > ---- +> --- > -URL scheme: `http://page.example.io` and `http://domain.com` +> URL scheme: `http://page.example.io` and `http://domain.com` In that case, the Pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside @@ -197,14 +197,14 @@ world. Custom domains are supported, but no TLS. ### Custom domains with TLS support ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate -- Secondary IP +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) +> - Wildcard TLS certificate +> - Secondary IP > ---- +> --- > -URL scheme: `https://page.example.io` and `https://domain.com` +> URL scheme: `https://page.example.io` and `https://domain.com` In that case, the Pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside @@ -251,9 +251,9 @@ Follow the steps below to configure verbose logging of GitLab Pages daemon. If you wish to make it log events with level `DEBUG` you must configure this in `/etc/gitlab/gitlab.rb`: - ```shell - gitlab_pages['log_verbose'] = true - ``` + ```shell + gitlab_pages['log_verbose'] = true + ``` 1. [Reconfigure GitLab][reconfigure] @@ -266,9 +266,9 @@ are stored. If you wish to store them in another location you must set it up in `/etc/gitlab/gitlab.rb`: - ```shell - gitlab_rails['pages_path'] = "/mnt/storage/pages" - ``` + ```shell + gitlab_rails['pages_path'] = "/mnt/storage/pages" + ``` 1. [Reconfigure GitLab][reconfigure] @@ -279,19 +279,19 @@ Omnibus GitLab 11.1. 1. By default the listener is configured to listen for requests on `localhost:8090`. - If you wish to disable it you must configure this in - `/etc/gitlab/gitlab.rb`: + If you wish to disable it you must configure this in + `/etc/gitlab/gitlab.rb`: - ```shell - gitlab_pages['listen_proxy'] = nil - ``` + ```shell + gitlab_pages['listen_proxy'] = nil + ``` - If you wish to make it listen on a different port you must configure this also in - `/etc/gitlab/gitlab.rb`: + If you wish to make it listen on a different port you must configure this also in + `/etc/gitlab/gitlab.rb`: - ```shell - gitlab_pages['listen_proxy'] = "localhost:10080" - ``` + ```shell + gitlab_pages['listen_proxy'] = "localhost:10080" + ``` 1. [Reconfigure GitLab][reconfigure] diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 4e40a7cb18d..295905a7625 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -89,11 +89,11 @@ since that is needed in all configurations. ### Wildcard domains >**Requirements:** -- [Wildcard DNS setup](#dns-configuration) +> - [Wildcard DNS setup](#dns-configuration) > ->--- +> --- > -URL scheme: `http://page.example.io` +> URL scheme: `http://page.example.io` This is the minimum setup that you can use Pages with. It is the base for all other setups as described below. Nginx will proxy all requests to the daemon. @@ -111,24 +111,24 @@ The Pages daemon doesn't listen to the outside world. 1. Go to the GitLab installation directory: - ```bash - cd /home/git/gitlab - ``` + ```bash + cd /home/git/gitlab + ``` 1. Edit `gitlab.yml` and under the `pages` setting, set `enabled` to `true` and the `host` to the FQDN under which GitLab Pages will be served: - ```yaml - ## GitLab Pages - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - # path: shared/pages + ```yaml + ## GitLab Pages + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + # path: shared/pages - host: example.io - port: 80 - https: false - ``` + host: example.io + port: 80 + https: false + ``` 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in order to enable the pages daemon. In `gitlab_pages_options` the @@ -151,13 +151,13 @@ The Pages daemon doesn't listen to the outside world. ### Wildcard domains with TLS support ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) +> - Wildcard TLS certificate > ->--- +> --- > -URL scheme: `https://page.example.io` +> URL scheme: `https://page.example.io` Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the outside world. @@ -174,17 +174,17 @@ outside world. 1. In `gitlab.yml`, set the port to `443` and https to `true`: - ```bash - ## GitLab Pages - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - # path: shared/pages - - host: example.io - port: 443 - https: true - ``` + ```bash + ## GitLab Pages + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + # path: shared/pages + + host: example.io + port: 443 + https: true + ``` 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in order to enable the pages daemon. In `gitlab_pages_options` the @@ -216,13 +216,13 @@ that without TLS certificates. ### Custom domains ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Secondary IP +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) +> - Secondary IP > ---- +> --- > -URL scheme: `http://page.example.io` and `http://domain.com` +> URL scheme: `http://page.example.io` and `http://domain.com` In that case, the pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside @@ -243,18 +243,18 @@ world. Custom domains are supported, but no TLS. `external_http` to the secondary IP on which the pages daemon will listen for connections: - ```yaml - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - # path: shared/pages + ```yaml + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + # path: shared/pages - host: example.io - port: 80 - https: false + host: example.io + port: 80 + https: false - external_http: 192.0.2.2:80 - ``` + external_http: 192.0.2.2:80 + ``` 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in order to enable the pages daemon. In `gitlab_pages_options` the @@ -281,14 +281,14 @@ world. Custom domains are supported, but no TLS. ### Custom domains with TLS support ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate -- Secondary IP +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) +> - Wildcard TLS certificate +> - Secondary IP > ---- +> --- > -URL scheme: `https://page.example.io` and `https://domain.com` +> URL scheme: `https://page.example.io` and `https://domain.com` In that case, the pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside @@ -309,20 +309,20 @@ world. Custom domains and TLS are supported. `external_http` and `external_https` to the secondary IP on which the pages daemon will listen for connections: - ```yaml - ## GitLab Pages - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - # path: shared/pages + ```yaml + ## GitLab Pages + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + # path: shared/pages - host: example.io - port: 443 - https: true + host: example.io + port: 443 + https: true - external_http: 192.0.2.2:80 - external_https: 192.0.2.2:443 - ``` + external_http: 192.0.2.2:80 + external_https: 192.0.2.2:443 + ``` 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in order to enable the pages daemon. In `gitlab_pages_options` the @@ -358,9 +358,9 @@ are stored. If you wish to store them in another location you must set it up in `/etc/gitlab/gitlab.rb`: - ```ruby - gitlab_rails['pages_path'] = "/mnt/storage/pages" - ``` + ```ruby + gitlab_rails['pages_path'] = "/mnt/storage/pages" + ``` 1. [Reconfigure GitLab][reconfigure] @@ -400,12 +400,12 @@ are stored. If you wish to store them in another location you must set it up in `gitlab.yml` under the `pages` section: - ```yaml - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - path: /mnt/storage/pages - ``` + ```yaml + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + path: /mnt/storage/pages + ``` 1. [Restart GitLab][restart] diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 96f436fa7c3..7ea7ed48850 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -5,36 +5,36 @@ GitLab allows you to define multiple repository storage paths to distribute the storage load between several mount points. ->**Notes:** +> **Notes:** > -- You must have at least one storage path called `default`. -- The paths are defined in key-value pairs. The key is an arbitrary name you - can pick to name the file path. -- The target directories and any of its subpaths must not be a symlink. +> - You must have at least one storage path called `default`. +> - The paths are defined in key-value pairs. The key is an arbitrary name you +> can pick to name the file path. +> - The target directories and any of its subpaths must not be a symlink. ## Configure GitLab ->**Warning:** -In order for [backups] to work correctly, the storage path must **not** be a -mount point and the GitLab user should have correct permissions for the parent -directory of the path. In Omnibus GitLab this is taken care of automatically, -but for source installations you should be extra careful. +> **Warning:** +> In order for [backups] to work correctly, the storage path must **not** be a +> mount point and the GitLab user should have correct permissions for the parent +> directory of the path. In Omnibus GitLab this is taken care of automatically, +> but for source installations you should be extra careful. > -The thing is that for compatibility reasons `gitlab.yml` has a different -structure than Omnibus. In `gitlab.yml` you indicate the path for the -repositories, for example `/home/git/repositories`, while in Omnibus you -indicate `git_data_dirs`, which for the example above would be `/home/git`. -Then, Omnibus will create a `repositories` directory under that path to use with -`gitlab.yml`. +> The thing is that for compatibility reasons `gitlab.yml` has a different +> structure than Omnibus. In `gitlab.yml` you indicate the path for the +> repositories, for example `/home/git/repositories`, while in Omnibus you +> indicate `git_data_dirs`, which for the example above would be `/home/git`. +> Then, Omnibus will create a `repositories` directory under that path to use with +> `gitlab.yml`. > -This little detail matters because while restoring a backup, the current -contents of `/home/git/repositories` [are moved to][raketask] `/home/git/repositories.old`, -so if `/home/git/repositories` is the mount point, then `mv` would be moving -things between mount points, and bad things could happen. Ideally, -`/home/git` would be the mount point, so then things would be moving within the -same mount point. This is guaranteed with Omnibus installations (because they -don't specify the full repository path but the parent path), but not for source -installations. +> This little detail matters because while restoring a backup, the current +> contents of `/home/git/repositories` [are moved to][raketask] `/home/git/repositories.old`, +> so if `/home/git/repositories` is the mount point, then `mv` would be moving +> things between mount points, and bad things could happen. Ideally, +> `/home/git` would be the mount point, so then things would be moving within the +> same mount point. This is guaranteed with Omnibus installations (because they +> don't specify the full repository path but the parent path), but not for source +> installations. --- diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index 9d157720ad2..7067958ecb4 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.md @@ -8,15 +8,15 @@ may not show up and merge requests may not be updated. The following are some troubleshooting steps that will help you diagnose the bottleneck. > **Note:** GitLab administrators/users should consider working through these -debug steps with GitLab Support so the backtraces can be analyzed by our team. -It may reveal a bug or necessary improvement in GitLab. - +> debug steps with GitLab Support so the backtraces can be analyzed by our team. +> It may reveal a bug or necessary improvement in GitLab. +> > **Note:** In any of the backtraces, be wary of suspecting cases where every - thread appears to be waiting in the database, Redis, or waiting to acquire - a mutex. This **may** mean there's contention in the database, for example, - but look for one thread that is different than the rest. This other thread - may be using all available CPU, or have a Ruby Global Interpreter Lock, - preventing other threads from continuing. +> thread appears to be waiting in the database, Redis, or waiting to acquire +> a mutex. This **may** mean there's contention in the database, for example, +> but look for one thread that is different than the rest. This other thread +> may be using all available CPU, or have a Ruby Global Interpreter Lock, +> preventing other threads from continuing. ## Thread dump diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 77e73b23021..467deb43644 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -50,9 +50,10 @@ _The uploads are stored by default in ### Using object storage ->**Notes:** -- [Introduced][ee-3867] in [GitLab Enterprise Edition Premium][eep] 10.5. -- Since version 11.1, we support direct_upload to S3. +> **Notes:** +> +> - [Introduced][ee-3867] in [GitLab Enterprise Edition Premium][eep] 10.5. +> - Since version 11.1, we support direct_upload to S3. If you don't want to use the local disk where GitLab is installed to store the uploads, you can use an object storage provider like AWS S3 instead. @@ -105,8 +106,8 @@ _The uploads are stored by default in } ``` ->**Note:** -If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs. + >**Note:** + If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs. ```ruby gitlab_rails['uploads_object_store_connection'] = { @@ -119,28 +120,28 @@ If you are using AWS IAM profiles, be sure to omit the AWS access key and secret 1. Save the file and [reconfigure GitLab][] for the changes to take effect. 1. Migrate any existing local uploads to the object storage: ->**Notes:** -These task complies with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. - - ```bash - # gitlab-rake gitlab:uploads:migrate[uploader_class, model_class, mount_point] - - # Avatars - gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" - gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" - gitlab-rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" - - # Attachments - gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" - gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" - gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" - - # Markdown - gitlab-rake "gitlab:uploads:migrate[FileUploader, Project]" - gitlab-rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" - gitlab-rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" - gitlab-rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" - ``` + > **Notes:** + > These task complies with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. + + ```bash + # gitlab-rake gitlab:uploads:migrate[uploader_class, model_class, mount_point] + + # Avatars + gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" + gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" + gitlab-rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" + + # Attachments + gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" + gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" + gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" + + # Markdown + gitlab-rake "gitlab:uploads:migrate[FileUploader, Project]" + gitlab-rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" + gitlab-rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" + gitlab-rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" + ``` --- @@ -167,32 +168,30 @@ _The uploads are stored by default in 1. Save the file and [restart GitLab][] for the changes to take effect. 1. Migrate any existing local uploads to the object storage: ->**Notes:** - -- These task comply with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. - -- To migrate in production use `RAILS_ENV=production` environment variable. - - ```bash - # sudo -u git -H bundle exec rake gitlab:uploads:migrate - - # Avatars - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" - - # Attachments - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" - - # Markdown - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, Project]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" - - ``` + > **Notes:** + > - These task comply with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. + > - To migrate in production use `RAILS_ENV=production` environment variable. + + ```bash + # sudo -u git -H bundle exec rake gitlab:uploads:migrate + + # Avatars + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" + + # Attachments + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" + + # Markdown + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, Project]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" + + ``` [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 4bf65a8fafd..5f9556726d1 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -319,7 +319,8 @@ Example of response ## Get job artifacts > **Notes**: -- [Introduced][ce-2893] in GitLab 8.5. +> +> - [Introduced][ce-2893] in GitLab 8.5. Get job artifacts of a project. @@ -350,7 +351,8 @@ Response: ## Download the artifacts archive > **Notes**: -- [Introduced][ce-5347] in GitLab 8.10. +> +> - [Introduced][ce-5347] in GitLab 8.10. Download the artifacts archive from the given reference name and job provided the job finished successfully. diff --git a/doc/api/services.md b/doc/api/services.md index 8c59b232b6d..741ea83070f 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -544,10 +544,10 @@ GET /projects/:id/services/jira Set JIRA service for a project. ->**Notes:** -- Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and - `project_url` are replaced by `project_key`, `url`. If you are using an - older version, [follow this documentation][old-jira-api]. +> **Notes:** +> - Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and +> `project_url` are replaced by `project_key`, `url`. If you are using an +> older version, [follow this documentation][old-jira-api]. ``` PUT /projects/:id/services/jira diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 98eae66469f..5752fb7c078 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -76,8 +76,8 @@ Below are the changes made between V3 and V4. - Simplify project payload exposed on Environment endpoints [!9675](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9675) - API uses merge request `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the merge requests, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530) - API uses issue `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the issues, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530) -- Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) -- Return correct `Link` header data for `GET /projects/:id/repository/commits` [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) +- Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) +- Return correct `Link` header data for `GET /projects/:id/repository/commits` [!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) - Update endpoints for repository files [!9637](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9637) - Moved `GET /projects/:id/repository/files?file_path=:file_path` to `GET /projects/:id/repository/files/:file_path` (`:file_path` should be URL-encoded) - `GET /projects/:id/repository/blobs/:sha` now returns JSON attributes for the blob identified by `:sha`, instead of finding the commit identified by `:sha` and returning the raw content of the blob in that commit identified by the required `?filepath=:filepath` diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 63338ff632c..54a8cfe7fd8 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -381,17 +381,18 @@ environment = ["DOCKER_DRIVER=overlay2"] If you're running multiple Runners you will have to modify all configuration files. > **Notes:** -- More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/). -- For more information about using OverlayFS with Docker, you can read - [Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). +> +> - More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/). +> - For more information about using OverlayFS with Docker, you can read +> [Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). ## Using the GitLab Container Registry > **Notes:** -- This feature requires GitLab 8.8 and GitLab Runner 1.2. -- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need - to pass a [personal access token][pat] instead of your password in order to - login to GitLab's Container Registry. +> - This feature requires GitLab 8.8 and GitLab Runner 1.2. +> - Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need +> to pass a [personal access token][pat] instead of your password in order to +> login to GitLab's Container Registry. Once you've built a Docker image, you can push it up to the built-in [GitLab Container Registry](../../user/project/container_registry.md). For example, diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 71f1d69cdf4..9abedcc6acb 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -452,13 +452,14 @@ that runner. ## Define an image from a private Container Registry > **Notes:** -- This feature requires GitLab Runner **1.8** or higher -- For GitLab Runner versions **>= 0.6, <1.8** there was a partial - support for using private registries, which required manual configuration - of credentials on runner's host. We recommend to upgrade your Runner to - at least version **1.8** if you want to use private registries. -- If the repository is private you need to authenticate your GitLab Runner in the - registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. +> +> - This feature requires GitLab Runner **1.8** or higher +> - For GitLab Runner versions **>= 0.6, <1.8** there was a partial +> support for using private registries, which required manual configuration +> of credentials on runner's host. We recommend to upgrade your Runner to +> at least version **1.8** if you want to use private registries. +> - If the repository is private you need to authenticate your GitLab Runner in the +> registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. As an example, let's assume that you want to use the `registry.example.com/private/image:latest` image which is private and requires you to login into a private container registry. @@ -475,57 +476,57 @@ To configure access for `registry.example.com`, follow these steps: 1. Find what the value of `DOCKER_AUTH_CONFIG` should be. There are two ways to accomplish this: - - **First way -** Do a `docker login` on your local machine: + - **First way -** Do a `docker login` on your local machine: - ```bash - docker login registry.example.com --username my_username --password my_password - ``` + ```bash + docker login registry.example.com --username my_username --password my_password + ``` - Then copy the content of `~/.docker/config.json`. - - **Second way -** In some setups, it's possible that Docker client will use + Then copy the content of `~/.docker/config.json`. + - **Second way -** In some setups, it's possible that Docker client will use the available system keystore to store the result of `docker login`. In that case, it's impossible to read `~/.docker/config.json`, so you will need to prepare the required base64-encoded version of `${username}:${password}` manually. Open a terminal and execute the following command: - ```bash - echo -n "my_username:my_password" | base64 + ```bash + echo -n "my_username:my_password" | base64 - # Example output to copy - bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= - ``` + # Example output to copy + bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= + ``` 1. Create a [variable] `DOCKER_AUTH_CONFIG` with the content of the Docker configuration file as the value: - ```json - { - "auths": { - "registry.example.com": { - "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" - } - } - } - ``` + ```json + { + "auths": { + "registry.example.com": { + "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" + } + } + } + ``` 1. Optionally,if you followed the first way of finding the `DOCKER_AUTH_CONFIG` value, do a `docker logout` on your computer if you don't need access to the registry from it: - ```bash - docker logout registry.example.com - ``` + ```bash + docker logout registry.example.com + ``` 1. You can now use any private image from `registry.example.com` defined in `image` and/or `services` in your `.gitlab-ci.yml` file: - ```yaml - image: my.registry.tld:5000/namespace/image:tag - ``` + ```yaml + image: my.registry.tld:5000/namespace/image:tag + ``` - In the example above, GitLab Runner will look at `my.registry.tld:5000` for the - image `namespace/image:tag`. + In the example above, GitLab Runner will look at `my.registry.tld:5000` for the + image `namespace/image:tag`. You can add configuration for as many registries as you want, adding more registries to the `"auths"` hash as described above. diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 8ea2e0a81dc..f1e5b00e927 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -87,18 +87,18 @@ will later see, is exposed in various places within GitLab. Each time a job that has an environment specified and succeeds, a deployment is recorded, remembering the Git SHA and environment name. ->**Note:** -Starting with GitLab 8.15, the environment name is exposed to the Runner in -two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is -the name given in `.gitlab-ci.yml` (with any variables expanded), while the -second is a "cleaned-up" version of the name, suitable for use in URLs, DNS, -etc. - ->**Note:** -Starting with GitLab 9.3, the environment URL is exposed to the Runner via -`$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if -the URL was not defined there, the external URL from the environment would be -used. +> **Note:** +> Starting with GitLab 8.15, the environment name is exposed to the Runner in +> two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is +> the name given in `.gitlab-ci.yml` (with any variables expanded), while the +> second is a "cleaned-up" version of the name, suitable for use in URLs, DNS, +> etc. +> +> **Note:** +> Starting with GitLab 9.3, the environment URL is exposed to the Runner via +> `$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if +> the URL was not defined there, the external URL from the environment would be +> used. To sum up, with the above `.gitlab-ci.yml` we have achieved that: @@ -134,14 +134,15 @@ There's a bunch of information there, specifically you can see: - A button that re-deploys the latest deployment, meaning it runs the job defined by the environment name for that specific commit ->**Notes:** -- While you can create environments manually in the web interface, we recommend - that you define your environments in `.gitlab-ci.yml` first. They will - be automatically created for you after the first deploy. -- The environments page can only be viewed by Reporters and above. For more - information on the permissions, see the [permissions documentation][permissions]. -- Only deploys that happen after your `.gitlab-ci.yml` is properly configured - will show up in the "Environment" and "Last deployment" lists. +> **Notes:** +> +> - While you can create environments manually in the web interface, we recommend +> that you define your environments in `.gitlab-ci.yml` first. They will +> be automatically created for you after the first deploy. +> - The environments page can only be viewed by Reporters and above. For more +> information on the permissions, see the [permissions documentation][permissions]. +> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured +> will show up in the "Environment" and "Last deployment" lists. The information shown in the Environments page is limited to the latest deployments, but as you may have guessed an environment can have multiple @@ -563,13 +564,13 @@ exist, you should see something like: ## Monitoring environments ->**Notes:** +> **Notes:** > -- For the monitoring dashboard to appear, you need to: - - Have enabled the [Prometheus integration][prom] - - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) -- With GitLab 9.2, all deployments to an environment are shown directly on the - monitoring dashboard +> - For the monitoring dashboard to appear, you need to: +> - Have enabled the [Prometheus integration][prom] +> - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) +> - With GitLab 9.2, all deployments to an environment are shown directly on the +> monitoring dashboard If you have enabled [Prometheus for monitoring system and response metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html), you can monitor the performance behavior of your app running in each environment. diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index a2de0408797..b2c73caae2e 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -85,7 +85,7 @@ When asked, answer `Y` to fetch and install dependencies. If everything went fine, you'll get an output like this: -![`mix phoenix.new`](img/mix-phoenix-new.png) +![mix phoenix.new](img/mix-phoenix-new.png) Now, our project is located inside the directory with the same name we pass to `mix` command, for example, `~/GitLab/hello_gitlab_ci`. @@ -145,7 +145,7 @@ Now, we have our app running locally. We can preview it directly on our browser. not work, open [`127.0.0.1:4000`](http://127.0.0.1:4000) instead and later, configure your OS to point `localhost` to `127.0.0.1`. -![`mix phoenix.server`](img/mix-phoenix-server.png) +![mix phoenix.server](img/mix-phoenix-server.png) Great, now we have a local Phoenix Server running our app. diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 286f3dee665..37078230b34 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -1,15 +1,16 @@ # Using Git submodules with GitLab CI > **Notes:** -- GitLab 8.12 introduced a new [CI job permissions model][newperms] and you - are encouraged to upgrade your GitLab instance if you haven't done already. - If you are **not** using GitLab 8.12 or higher, you would need to work your way - around submodules in order to access the sources of e.g., `gitlab.com/group/project` - with the use of [SSH keys](ssh_keys/README.md). -- With GitLab 8.12 onward, your permissions are used to evaluate what a CI job - can access. More information about how this system works can be found in the - [Jobs permissions model](../user/permissions.md#job-permissions). -- The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. +> +> - GitLab 8.12 introduced a new [CI job permissions model][newperms] and you +> are encouraged to upgrade your GitLab instance if you haven't done already. +> If you are **not** using GitLab 8.12 or higher, you would need to work your way +> around submodules in order to access the sources of e.g., `gitlab.com/group/project` +> with the use of [SSH keys](ssh_keys/README.md). +> - With GitLab 8.12 onward, your permissions are used to evaluate what a CI job +> can access. More information about how this system works can be found in the +> [Jobs permissions model](../user/permissions.md#job-permissions). +> - The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. ## Configuring the `.gitmodules` file diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 28c484ddbe6..1b17f6ac5ea 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,10 +1,9 @@ # Getting started with Review Apps -> -- [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab - 8.13 and 8.14. -- Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by - [Fourchette]. +> - [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab +> 8.13 and 8.14. +> - Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by +> [Fourchette]. The basis of Review Apps is the [dynamic environments] which allow you to create a new environment (dynamically) for each one of your branches. diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 8f1ff190804..7859d2ec631 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -144,9 +144,8 @@ An admin can enable/disable a specific Runner for projects: ## Protected Runners -> -[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) -in GitLab 10.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) +> in GitLab 10.0. You can protect Runners from revealing sensitive information. Whenever a Runner is protected, the Runner picks only jobs created on diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index 4cb05509e7b..0c3b0bf6990 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -46,7 +46,7 @@ to access it. This is where an SSH key pair comes in handy. 1. You will first need to create an SSH key pair. For more information, follow the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair). - **Do not** add a passphrase to the SSH key, or the `before_script` will\ + **Do not** add a passphrase to the SSH key, or the `before_script` will prompt for it. 1. Create a new [variable](../variables/README.md#variables). @@ -175,7 +175,7 @@ Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the [content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor) above, here's what more you need to add: - ```yaml +```yaml before_script: ## ## Assuming you created the SSH_KNOWN_HOSTS variable, uncomment the diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index c213b096a14..cf92d90ba30 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -1,9 +1,10 @@ # Triggering pipelines through the API > **Notes**: -- [Introduced][ci-229] in GitLab CE 7.14. -- GitLab 8.12 has a completely redesigned job permissions system. Read all - about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers). +> +> - [Introduced][ci-229] in GitLab CE 7.14. +> - GitLab 8.12 has a completely redesigned job permissions system. Read all +> about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers). Triggers can be used to force a pipeline rerun of a specific `ref` (branch or tag) with an API call. @@ -49,11 +50,12 @@ The action is irreversible. ## Triggering a pipeline > **Notes**: -- Valid refs are only the branches and tags. If you pass a commit SHA as a ref, - it will not trigger a job. -- If your project is public, passing the token in plain text is probably not the - wisest idea, so you might want to use a - [variable](../variables/README.md#variables) for that purpose. +> +> - Valid refs are only the branches and tags. If you pass a commit SHA as a ref, +> it will not trigger a job. +> - If your project is public, passing the token in plain text is probably not the +> wisest idea, so you might want to use a +> [variable](../variables/README.md#variables) for that purpose. To trigger a job you need to send a `POST` request to GitLab's API endpoint: @@ -122,11 +124,12 @@ Now, whenever a new tag is pushed on project A, the job will run and the ## Triggering a pipeline from a webhook > **Notes**: -- Introduced in GitLab 8.14. -- `ref` should be passed as part of the URL in order to take precedence over - `ref` from the webhook body that designates the branch ref that fired the - trigger in the source repository. -- `ref` should be URL-encoded if it contains slashes. +> +> - Introduced in GitLab 8.14. +> - `ref` should be passed as part of the URL in order to take precedence over +> `ref` from the webhook body that designates the branch ref that fired the +> trigger in the source repository. +> - `ref` should be URL-encoded if it contains slashes. To trigger a job from a webhook of another project you need to add the following webhook URL for Push and Tag events (change the project ID, ref and token): diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index c1ebe39e076..d89705e8ead 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -383,7 +383,7 @@ except master. ## `only` and `except` (complex) > `refs` and `kubernetes` policies introduced in GitLab 10.0 - +> > `variables` policy introduced in 10.7 CAUTION: **Warning:** @@ -583,9 +583,10 @@ The above script will: ### `when:manual` > **Notes:** -- Introduced in GitLab 8.10. -- Blocking manual actions were introduced in GitLab 9.0. -- Protected actions were introduced in GitLab 9.2. +> +> - Introduced in GitLab 8.10. +> - Blocking manual actions were introduced in GitLab 9.0. +> - Protected actions were introduced in GitLab 9.2. Manual actions are a special type of job that are not executed automatically, they need to be explicitly started by a user. An example usage of manual actions @@ -616,11 +617,11 @@ have ability to merge to this branch. ## `environment` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.9. -- You can read more about environments and find more examples in the - [documentation about environments][environment]. +> - Introduced in GitLab 8.9. +> - You can read more about environments and find more examples in the +> [documentation about environments][environment]. `environment` is used to define that a job deploys to a specific environment. If `environment` is specified and no environment under that name exists, a new @@ -641,15 +642,15 @@ deployment to the `production` environment. ### `environment:name` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.11. -- Before GitLab 8.11, the name of an environment could be defined as a string like - `environment: production`. The recommended way now is to define it under the - `name` keyword. -- The `name` parameter can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - Introduced in GitLab 8.11. +> - Before GitLab 8.11, the name of an environment could be defined as a string like +> `environment: production`. The recommended way now is to define it under the +> `name` keyword. +> - The `name` parameter can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. The `environment` name can contain: @@ -680,14 +681,14 @@ deploy to production: ### `environment:url` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.11. -- Before GitLab 8.11, the URL could be added only in GitLab's UI. The - recommended way now is to define it in `.gitlab-ci.yml`. -- The `url` parameter can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - Introduced in GitLab 8.11. +> - Before GitLab 8.11, the URL could be added only in GitLab's UI. The +> recommended way now is to define it in `.gitlab-ci.yml`. +> - The `url` parameter can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. This is an optional value that when set, it exposes buttons in various places in GitLab which when clicked take you to the defined URL. @@ -707,12 +708,12 @@ deploy to production: ### `environment:on_stop` +> **Notes:** > -**Notes:** -- [Introduced][ce-6669] in GitLab 8.13. -- Starting with GitLab 8.14, when you have an environment that has a stop action - defined, GitLab will automatically trigger a stop action when the associated - branch is deleted. +> - [Introduced][ce-6669] in GitLab 8.13. +> - Starting with GitLab 8.14, when you have an environment that has a stop action +> defined, GitLab will automatically trigger a stop action when the associated +> branch is deleted. Closing (stoping) environments can be achieved with the `on_stop` keyword defined under `environment`. It declares a different job that runs in order to close @@ -763,13 +764,13 @@ The `stop_review_app` job is **required** to have the following keywords defined ### Dynamic environments +> **Notes:** > -**Notes:** -- [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. -- The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15. -- The `name` and `url` parameters can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. +> - The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15. +> - The `name` and `url` parameters can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. For example: @@ -799,13 +800,13 @@ as Review Apps. You can see a simple example using Review Apps at ## `cache` +> **Notes:** > -**Notes:** -- Introduced in GitLab Runner v0.7.0. -- `cache` can be set globally and per-job. -- From GitLab 9.0, caching is enabled and shared between pipelines and jobs - by default. -- From GitLab 9.2, caches are restored before [artifacts](#artifacts). +> - Introduced in GitLab Runner v0.7.0. +> - `cache` can be set globally and per-job. +> - From GitLab 9.0, caching is enabled and shared between pipelines and jobs +> by default. +> - From GitLab 9.2, caches are restored before [artifacts](#artifacts). TIP: **Learn more:** Read how caching works and find out some good practices in the @@ -967,13 +968,13 @@ skip the download step. ## `artifacts` +> **Notes:** > -**Notes:** -- Introduced in GitLab Runner v0.7.0 for non-Windows platforms. -- Windows support was added in GitLab Runner v.1.0.0. -- From GitLab 9.2, caches are restored before artifacts. -- Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). -- Job artifacts are only collected for successful jobs by default. +> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms. +> - Windows support was added in GitLab Runner v.1.0.0. +> - From GitLab 9.2, caches are restored before artifacts. +> - Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). +> - Job artifacts are only collected for successful jobs by default. `artifacts` is used to specify a list of files and directories which should be attached to the job after success. diff --git a/doc/development/automatic_ce_ee_merge.md b/doc/development/automatic_ce_ee_merge.md index 8d41503f874..f6509b5c1dd 100644 --- a/doc/development/automatic_ce_ee_merge.md +++ b/doc/development/automatic_ce_ee_merge.md @@ -9,16 +9,16 @@ This merge is done automatically in a ## What to do if you are pinged in a `CE Upstream` merge request to resolve a conflict? 1. Please resolve the conflict as soon as possible or ask someone else to do it - - It's ok to resolve more conflicts than the one that you are asked to resolve. - In that case, it's a good habit to ask for a double-check on your resolution - by someone who is familiar with the code you touched. + - It's ok to resolve more conflicts than the one that you are asked to resolve. + In that case, it's a good habit to ask for a double-check on your resolution + by someone who is familiar with the code you touched. 1. Once you have resolved your conflicts, push to the branch (no force-push) 1. Assign the merge request to the next person that has to resolve a conflict 1. If all conflicts are resolved after your resolution is pushed, keep the merge - request assigned to you: **you are now responsible for the merge request to be - green** + request assigned to you: **you are now responsible for the merge request to be + green** 1. If you need any help, you can ping the current [release managers], or ask in - the `#ce-to-ee` Slack channel + the `#ce-to-ee` Slack channel A few notes about the automatic CE->EE merge job: @@ -127,19 +127,19 @@ Now, every time you create an MR for CE and EE: 1. Open two terminal windows, one in CE, and another one in EE 1. In the CE terminal: - 1. Create the CE branch, e.g., `branch-example` - 1. Make your changes and push a commit (commit A) - 1. Create the CE merge request in GitLab + 1. Create the CE branch, e.g., `branch-example` + 1. Make your changes and push a commit (commit A) + 1. Create the CE merge request in GitLab 1. In the EE terminal: - 1. Create the EE-equivalent branch ending with `-ee`, e.g., - `git checkout -b branch-example-ee` - 1. Fetch the CE branch: `git fetch ce branch-example` - 1. Cherry-pick the commit A: `git cherry-pick commit-A-SHA` - 1. If Git prompts you to fix the conflicts, do a `git status` - to check which files contain conflicts, fix them, save the files - 1. Add the changes with `git add .` but **DO NOT commit** them - 1. Continue cherry-picking: `git cherry-pick --continue` - 1. Push to EE: `git push origin branch-example-ee` + 1. Create the EE-equivalent branch ending with `-ee`, e.g., + `git checkout -b branch-example-ee` + 1. Fetch the CE branch: `git fetch ce branch-example` + 1. Cherry-pick the commit A: `git cherry-pick commit-A-SHA` + 1. If Git prompts you to fix the conflicts, do a `git status` + to check which files contain conflicts, fix them, save the files + 1. Add the changes with `git add .` but **DO NOT commit** them + 1. Continue cherry-picking: `git cherry-pick --continue` + 1. Push to EE: `git push origin branch-example-ee` 1. Create the EE-equivalent MR and link to the CE MR from the description "Ports [CE-MR-LINK] to EE" 1. Once all the jobs are passing in both CE and EE, you've addressed the diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index f0d5af9fcb5..bb9a296ef12 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -10,10 +10,10 @@ migrations automatically reschedule themselves for a later point in time. ## When To Use Background Migrations ->**Note:** -When adding background migrations _you must_ make sure they are announced in the -monthly release post along with an estimate of how long it will take to complete -the migrations. +> **Note:** +> When adding background migrations _you must_ make sure they are announced in the +> monthly release post along with an estimate of how long it will take to complete +> the migrations. In the vast majority of cases you will want to use a regular Rails migration instead. Background migrations should _only_ be used when migrating _data_ in @@ -127,23 +127,23 @@ big JSON blob) to column `bar` (containing a string). The process for this would roughly be as follows: 1. Release A: - 1. Create a migration class that perform the migration for a row with a given ID. - 1. Deploy the code for this release, this should include some code that will - schedule jobs for newly created data (e.g. using an `after_create` hook). - 1. Schedule jobs for all existing rows in a post-deployment migration. It's - possible some newly created rows may be scheduled twice so your migration - should take care of this. + 1. Create a migration class that perform the migration for a row with a given ID. + 1. Deploy the code for this release, this should include some code that will + schedule jobs for newly created data (e.g. using an `after_create` hook). + 1. Schedule jobs for all existing rows in a post-deployment migration. It's + possible some newly created rows may be scheduled twice so your migration + should take care of this. 1. Release B: - 1. Deploy code so that the application starts using the new column and stops - scheduling jobs for newly created data. - 1. In a post-deployment migration you'll need to ensure no jobs remain. - 1. Use `Gitlab::BackgroundMigration.steal` to process any remaining - jobs in Sidekiq. - 1. Reschedule the migration to be run directly (i.e. not through Sidekiq) - on any rows that weren't migrated by Sidekiq. This can happen if, for - instance, Sidekiq received a SIGKILL, or if a particular batch failed - enough times to be marked as dead. - 1. Remove the old column. + 1. Deploy code so that the application starts using the new column and stops + scheduling jobs for newly created data. + 1. In a post-deployment migration you'll need to ensure no jobs remain. + 1. Use `Gitlab::BackgroundMigration.steal` to process any remaining + jobs in Sidekiq. + 1. Reschedule the migration to be run directly (i.e. not through Sidekiq) + on any rows that weren't migrated by Sidekiq. This can happen if, for + instance, Sidekiq received a SIGKILL, or if a particular batch failed + enough times to be marked as dead. + 1. Remove the old column. This may also require a bump to the [import/export version][import-export], if importing a project from a prior version of GitLab requires the data to be in diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 23c80799235..e50e6370c80 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -5,30 +5,30 @@ There are a few rules to get your merge request accepted: 1. Your merge request should only be **merged by a [maintainer][team]**. - 1. If your merge request includes only backend changes [^1], it must be - **approved by a [backend maintainer][projects]**. - 1. If your merge request includes only frontend changes [^1], it must be - **approved by a [frontend maintainer][projects]**. - 1. If your merge request includes UX changes [^1], it must - be **approved by a [UX team member][team]**. - 1. If your merge request includes adding a new JavaScript library [^1], it must be - **approved by a [frontend lead][team]**. - 1. If your merge request includes adding a new UI/UX paradigm [^1], it must be - **approved by a [UX lead][team]**. - 1. If your merge request includes frontend and backend changes [^1], it must - be **approved by a [frontend and a backend maintainer][projects]**. - 1. If your merge request includes UX and frontend changes [^1], it must - be **approved by a [UX team member and a frontend maintainer][team]**. - 1. If your merge request includes UX, frontend and backend changes [^1], it must - be **approved by a [UX team member, a frontend and a backend maintainer][team]**. - 1. If your merge request includes a new dependency or a filesystem change, it must - be *approved by a [Distribution team member][team]*. See how to work with the [Distribution team for more details.](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/) + 1. If your merge request includes only backend changes [^1], it must be + **approved by a [backend maintainer][projects]**. + 1. If your merge request includes only frontend changes [^1], it must be + **approved by a [frontend maintainer][projects]**. + 1. If your merge request includes UX changes [^1], it must + be **approved by a [UX team member][team]**. + 1. If your merge request includes adding a new JavaScript library [^1], it must be + **approved by a [frontend lead][team]**. + 1. If your merge request includes adding a new UI/UX paradigm [^1], it must be + **approved by a [UX lead][team]**. + 1. If your merge request includes frontend and backend changes [^1], it must + be **approved by a [frontend and a backend maintainer][projects]**. + 1. If your merge request includes UX and frontend changes [^1], it must + be **approved by a [UX team member and a frontend maintainer][team]**. + 1. If your merge request includes UX, frontend and backend changes [^1], it must + be **approved by a [UX team member, a frontend and a backend maintainer][team]**. + 1. If your merge request includes a new dependency or a filesystem change, it must + be *approved by a [Distribution team member][team]*. See how to work with the [Distribution team for more details.](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/) 1. To lower the amount of merge requests maintainers need to review, you can - ask or assign any [reviewers][projects] for a first review. - 1. If you need some guidance (e.g. it's your first merge request), feel free - to ask one of the [Merge request coaches][team]. - 1. The reviewer will assign the merge request to a maintainer once the - reviewer is satisfied with the state of the merge request. + ask or assign any [reviewers][projects] for a first review. + 1. If you need some guidance (e.g. it's your first merge request), feel free + to ask one of the [Merge request coaches][team]. + 1. The reviewer will assign the merge request to a maintainer once the + reviewer is satisfied with the state of the merge request. 1. Keep in mind that maintainers are also going to perform a final code review. The ideal scenario is that the reviewer has already addressed any concerns the maintainer would have found, and the maintainer only has to perform the @@ -160,41 +160,41 @@ Enterprise Edition instance. This has some implications: 1. **Query changes** should be tested to ensure that they don't result in worse performance at the scale of GitLab.com: - 1. Generating large quantities of data locally can help. - 2. Asking for query plans from GitLab.com is the most reliable way to validate - these. + 1. Generating large quantities of data locally can help. + 2. Asking for query plans from GitLab.com is the most reliable way to validate + these. 2. **Database migrations** must be: - 1. Reversible. - 2. Performant at the scale of GitLab.com - ask a maintainer to test the - migration on the staging environment if you aren't sure. - 3. Categorised correctly: - - Regular migrations run before the new code is running on the instance. - - [Post-deployment migrations](post_deployment_migrations.md) run _after_ - the new code is deployed, when the instance is configured to do that. - - [Background migrations](background_migrations.md) run in Sidekiq, and - should only be done for migrations that would take an extreme amount of - time at GitLab.com scale. + 1. Reversible. + 2. Performant at the scale of GitLab.com - ask a maintainer to test the + migration on the staging environment if you aren't sure. + 3. Categorised correctly: + - Regular migrations run before the new code is running on the instance. + - [Post-deployment migrations](post_deployment_migrations.md) run _after_ + the new code is deployed, when the instance is configured to do that. + - [Background migrations](background_migrations.md) run in Sidekiq, and + should only be done for migrations that would take an extreme amount of + time at GitLab.com scale. 3. **Sidekiq workers** [cannot change in a backwards-incompatible way](sidekiq_style_guide.md#removing-or-renaming-queues): - 1. Sidekiq queues are not drained before a deploy happens, so there will be - workers in the queue from the previous version of GitLab. - 2. If you need to change a method signature, try to do so across two releases, - and accept both the old and new arguments in the first of those. - 3. Similarly, if you need to remove a worker, stop it from being scheduled in - one release, then remove it in the next. This will allow existing jobs to - execute. - 4. Don't forget, not every instance will upgrade to every intermediate version - (some people may go from X.1.0 to X.10.0, or even try bigger upgrades!), so - try to be liberal in accepting the old format if it is cheap to do so. + 1. Sidekiq queues are not drained before a deploy happens, so there will be + workers in the queue from the previous version of GitLab. + 2. If you need to change a method signature, try to do so across two releases, + and accept both the old and new arguments in the first of those. + 3. Similarly, if you need to remove a worker, stop it from being scheduled in + one release, then remove it in the next. This will allow existing jobs to + execute. + 4. Don't forget, not every instance will upgrade to every intermediate version + (some people may go from X.1.0 to X.10.0, or even try bigger upgrades!), so + try to be liberal in accepting the old format if it is cheap to do so. 4. **Cached values** may persist across releases. If you are changing the type a cached value returns (say, from a string or nil to an array), change the cache key at the same time. 5. **Settings** should be added as a [last resort](https://about.gitlab.com/handbook/product/#convention-over-configuration). If you're adding a new setting in `gitlab.yml`: - 1. Try to avoid that, and add to `ApplicationSetting` instead. - 2. Ensure that it is also - [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml). + 1. Try to avoid that, and add to `ApplicationSetting` instead. + 2. Ensure that it is also + [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml). 6. **Filesystem access** can be slow, so try to avoid [shared files](shared_files.md) when an alternative solution is available. diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 64f5a2c8022..eac7cb44c40 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -16,7 +16,7 @@ - [Milestone labels](#milestone-labels) - [Bug Priority labels](#bug-priority-labels) - [Bug Severity labels](#bug-severity-labels) - - [Severity impact guidance](#severity-impact-guidance) + - [Severity impact guidance](#severity-impact-guidance) - [Label for community contributors](#label-for-community-contributors) - [Implement design & UI elements](#implement-design--ui-elements) - [Issue tracker](#issue-tracker) diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 6a334e9b17d..08042fa2aec 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -9,7 +9,7 @@ - [Release Scoping labels](#release-scoping-labels) - [Priority labels](#priority-labels) - [Severity labels](#severity-labels) - - [Severity impact guidance](#severity-impact-guidance) + - [Severity impact guidance](#severity-impact-guidance) - [Label for community contributors](#label-for-community-contributors) - [Issue triaging](#issue-triaging) - [Feature proposals](#feature-proposals) @@ -250,7 +250,7 @@ code snippet right after your description in a new line: `~"feature proposal"`. 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-ce/blob/master/.gitlab/issue_templates/Feature Proposal.md) provided on the issue tracker. +Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature%20Proposal.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 9b1da4e7bc1..685287f7a0c 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -55,30 +55,30 @@ request is as follows: organized commits by [squashing them][git-squash] 1. Push the commit(s) to your fork 1. Submit a merge request (MR) to the `master` branch - 1. Your merge request needs at least 1 approval but feel free to require more. - For instance if you're touching backend and frontend code, it's a good idea - to require 2 approvals: 1 from a backend maintainer and 1 from a frontend - maintainer - 1. You don't have to select any approvers, but you can if you really want - specific people to approve your merge request + 1. Your merge request needs at least 1 approval but feel free to require more. + For instance if you're touching backend and frontend code, it's a good idea + to require 2 approvals: 1 from a backend maintainer and 1 from a frontend + maintainer + 1. You don't have to select any approvers, but you can if you really want + specific people to approve your merge request 1. The MR title should describe the change you want to make 1. The MR description should give a motive for your change and the method you used to achieve it. - 1. If you are contributing code, fill in the template already provided in the - "Description" field. - 1. If you are contributing documentation, choose `Documentation` from the - "Choose a template" menu and fill in the template. - 1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or - `Closes #XXX` syntax to auto-close the issue(s) once the merge request will - be merged. + 1. If you are contributing code, fill in the template already provided in the + "Description" field. + 1. If you are contributing documentation, choose `Documentation` from the + "Choose a template" menu and fill in the template. + 1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or + `Closes #XXX` syntax to auto-close the issue(s) once the merge request will + be merged. 1. If you're allowed to, set a relevant milestone and labels 1. If the MR changes the UI it should include *Before* and *After* screenshots 1. If the MR changes CSS classes please include the list of affected pages, `grep css-class ./app -R` 1. Be prepared to answer questions and incorporate feedback even if requests for this arrive weeks or months after your MR submission - 1. If a discussion has been addressed, select the "Resolve discussion" button - beneath it to mark it resolved. + 1. If a discussion has been addressed, select the "Resolve discussion" button + beneath it to mark it resolved. 1. If your MR touches code that executes shell commands, reads or opens files or handles paths to files on disk, make sure it adheres to the [shell command guidelines](../shell_commands.md) @@ -138,7 +138,7 @@ When having your code reviewed and when reviewing merge requests please take the making and testing future changes 1. Changes do not adversely degrade performance. - Avoid repeated polling of endpoints that require a significant amount of overhead - - Check for N+1 queries via the SQL log or [`QueryRecorder`](https://docs.gitlab.com/ce/development/mer ge_request_performance_guidelines.html) + - Check for N+1 queries via the SQL log or [`QueryRecorder`](https://docs.gitlab.com/ce/development/merge_request_performance_guidelines.html) - Avoid repeated access of filesystem 1. If you need polling to support real-time features, please use [polling with ETag caching][polling-etag]. diff --git a/doc/development/diffs.md b/doc/development/diffs.md index 725507b7ef6..2738b1b5635 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -26,11 +26,11 @@ In order to present diffs information on the Merge Request diffs page, we: 1. Fetch all diff files from database `merge_request_diff_files` 2. Fetch the _old_ and _new_ file blobs in batch to: - 1. Highlight old and new file content - 2. Know which viewer it should use for each file (text, image, deleted, etc) - 3. Know if the file content changed - 4. Know if it was stored externally - 5. Know if it had storage errors + 1. Highlight old and new file content + 2. Know which viewer it should use for each file (text, image, deleted, etc) + 3. Know if the file content changed + 4. Know if it was stored externally + 5. Know if it had storage errors 3. If the diff file is cacheable (text-based), it's cached on Redis using `Gitlab::Diff::FileCollection::MergeRequestDiff` diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 6c60a517b6d..e610c7595a8 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -297,10 +297,10 @@ avoid duplication, link to the special document that can be found in [`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will read like: - ``` - Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) - for the changes to take effect. - ``` +``` +Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) +for the changes to take effect. +``` If the document you are editing resides in a place other than the GitLab CE/EE `doc/` directory, instead of the relative link, use the full path: diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 1cd873b6fe3..f9e6efa2c30 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -166,47 +166,53 @@ There are a few gotchas with it: to make it call the other method we want to extend, like a [template method pattern](https://en.wikipedia.org/wiki/Template_method_pattern). For example, given this base: - ``` ruby - class Base - def execute - return unless enabled? - # ... - # ... - end - end - ``` - Instead of just overriding `Base#execute`, we should update it and extract - the behaviour into another method: - ``` ruby - class Base - def execute - return unless enabled? - - do_something + ```ruby + class Base + def execute + return unless enabled? + + # ... + # ... + end end + ``` - private + Instead of just overriding `Base#execute`, we should update it and extract + the behaviour into another method: - def do_something - # ... - # ... + ```ruby + class Base + def execute + return unless enabled? + + do_something + end + + private + + def do_something + # ... + # ... + end end - end - ``` - Then we're free to override that `do_something` without worrying about the - guards: - ``` ruby - module EE::Base - extend ::Gitlab::Utils::Override - - override :do_something - def do_something - # Follow the above pattern to call super and extend it + ``` + + Then we're free to override that `do_something` without worrying about the + guards: + + ```ruby + module EE::Base + extend ::Gitlab::Utils::Override + + override :do_something + def do_something + # Follow the above pattern to call super and extend it + end end - end - ``` - This would require updating CE first, or make sure this is back ported to CE. + ``` + + This would require updating CE first, or make sure this is back ported to CE. When prepending, place them in the `ee/` specific sub-directory, and wrap class or module in `module EE` to avoid naming conflicts. @@ -469,7 +475,7 @@ Put the EE module files following For EE API routes, we put them in a `prepended` block: -``` ruby +```ruby module EE module API module MergeRequests @@ -503,7 +509,7 @@ interface first here. For example, suppose we have a few more optional params for EE, given this CE API code: -``` ruby +```ruby module API class MergeRequests < Grape::API # EE::API::MergeRequests would override the following helpers @@ -525,7 +531,7 @@ end And then we could override it in EE module: -``` ruby +```ruby module EE module API module MergeRequests @@ -552,7 +558,7 @@ To make it easy for an EE module to override the CE helpers, we need to define those helpers we want to extend first. Try to do that immediately after the class definition to make it easy and clear: -``` ruby +```ruby module API class JobArtifacts < Grape::API # EE::API::JobArtifacts would override the following helpers @@ -569,7 +575,7 @@ end And then we can follow regular object-oriented practices to override it: -``` ruby +```ruby module EE module API module JobArtifacts @@ -596,7 +602,7 @@ therefore can't be simply overridden. We need to extract them into a standalone method, or introduce some "hooks" where we could inject behavior in the CE route. Something like this: -``` ruby +```ruby module API class MergeRequests < Grape::API helpers do @@ -623,7 +629,7 @@ end Note that `update_merge_request_ee` doesn't do anything in CE, but then we could override it in EE: -``` ruby +```ruby module EE module API module MergeRequests @@ -662,7 +668,7 @@ For example, in one place we need to pass an extra argument to `at_least_one_of` so that the API could consider an EE-only argument as the least argument. This is not quite beautiful but it's working: -``` ruby +```ruby module API class MergeRequests < Grape::API def self.update_params_at_least_one_of @@ -683,7 +689,7 @@ end And then we could easily extend that argument in the EE class method: -``` ruby +```ruby module EE module API module MergeRequests diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index da836a0e82e..ef0eed786d2 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -74,7 +74,7 @@ bundle and included on the page. > `content_for :page_specific_javascripts` within haml files, along with > manually generated webpack bundles. However under this new system you should > not ever need to manually add an entry point to the `webpack.config.js` file. - +> > **Tip:** > If you are unsure what controller and action corresponds to a given page, you > can find this out by inspecting `document.body.dataset.page` within your @@ -109,7 +109,6 @@ bundle and included on the page. `my_widget.js` is only imported within `pages/widget/show/index.js`, you should place the module at `pages/widget/show/my_widget.js` and import it with a relative path (e.g. `import initMyWidget from './my_widget';`). - - If a class or module is _used by multiple routes_, place it within a shared directory at the closest common parent directory for the entry points that import it. For example, if `my_widget.js` is imported within diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 284b4b53334..656ddd868cd 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -17,74 +17,81 @@ at the top, but legacy files are a special case. Any time you develop a new fea refactor an existing one, you should abide by the eslint rules. 1. **Never Ever EVER** disable eslint globally for a file - ```javascript - // bad - /* eslint-disable */ - - // better - /* eslint-disable some-rule, some-other-rule */ - // best - // nothing :) - ``` + ```javascript + // bad + /* eslint-disable */ + + // better + /* eslint-disable some-rule, some-other-rule */ + + // best + // nothing :) + ``` 1. If you do need to disable a rule for a single violation, try to do it as locally as possible - ```javascript - // bad - /* eslint-disable no-new */ - - import Foo from 'foo'; - - new Foo(); - // better - import Foo from 'foo'; + ```javascript + // bad + /* eslint-disable no-new */ + + import Foo from 'foo'; + + new Foo(); + + // better + import Foo from 'foo'; + + // eslint-disable-next-line no-new + new Foo(); + ``` - // eslint-disable-next-line no-new - new Foo(); - ``` 1. There are few rules that we need to disable due to technical debt. Which are: - 1. [no-new][eslint-new] - 1. [class-methods-use-this][eslint-this] + 1. [no-new][eslint-new] + 1. [class-methods-use-this][eslint-this] 1. When they are needed _always_ place ESlint directive comment blocks on the first line of a script, followed by any global declarations, then a blank newline prior to any imports or code. - ```javascript - // bad - /* global Foo */ - /* eslint-disable no-new */ - import Bar from './bar'; - - // good - /* eslint-disable no-new */ - /* global Foo */ - import Bar from './bar'; - ``` + ```javascript + // bad + /* global Foo */ + /* eslint-disable no-new */ + import Bar from './bar'; + + // good + /* eslint-disable no-new */ + /* global Foo */ + + import Bar from './bar'; + ``` 1. **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead. 1. When declaring multiple globals, always use one `/* global [name] */` line per variable. - ```javascript - // bad - /* globals Flash, Cookies, jQuery */ - // good - /* global Flash */ - /* global Cookies */ - /* global jQuery */ - ``` + ```javascript + // bad + /* globals Flash, Cookies, jQuery */ + + // good + /* global Flash */ + /* global Cookies */ + /* global jQuery */ + ``` 1. Use up to 3 parameters for a function or class. If you need more accept an Object instead. - ```javascript - // bad - fn(p1, p2, p3, p4) {} - // good - fn(options) {} - ``` + ```javascript + // bad + fn(p1, p2, p3, p4) {} + + // good + fn(options) {} + ``` #### Modules, Imports, and Exports + 1. Use ES module syntax to import modules ```javascript // bad @@ -178,109 +185,116 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ``` #### Data Mutation and Pure functions + 1. Strive to write many small pure functions, and minimize where mutations occur. - ```javascript + + ```javascript // bad const values = {foo: 1}; - + function impureFunction(items) { const bar = 1; - + items.foo = items.a * bar + 2; - + return items.a; } - + const c = impureFunction(values); - + // good var values = {foo: 1}; - + function pureFunction (foo) { var bar = 1; - + foo = foo * bar + 2; - + return foo; } - + var c = pureFunction(values.foo); - ``` + ``` 1. Avoid constructors with side-effects. -Although we aim for code without side-effects we need some side-effects for our code to run. - -If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.) - -```javascript -// Bad -export class Foo { - constructor() { - this.init(); - } - init() { - document.addEventListener('click', this.handleCallback) - }, - handleCallback() { - - } -} - -// Good -export class Foo { - constructor() { - document.addEventListener() - } - handleCallback() { - } -} -``` - -On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized outside of the constructor. + Although we aim for code without side-effects we need some side-effects for our code to run. -1. Prefer `.map`, `.reduce` or `.filter` over `.forEach` -A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`, -`.reduce` or `.filter` - ```javascript - const users = [ { name: 'Foo' }, { name: 'Bar' } ]; + If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.) - // bad - users.forEach((user, index) => { - user.id = index; - }); + ```javascript + // Bad + export class Foo { + constructor() { + this.init(); + } + init() { + document.addEventListener('click', this.handleCallback) + }, + handleCallback() { + + } + } + + // Good + export class Foo { + constructor() { + document.addEventListener() + } + handleCallback() { + } + } + ``` - // good - const usersWithId = users.map((user, index) => { - return Object.assign({}, user, { id: index }); - }); - ``` + On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized outside of the constructor. + +1. Prefer `.map`, `.reduce` or `.filter` over `.forEach` + A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`, + `.reduce` or `.filter` + + ```javascript + const users = [ { name: 'Foo' }, { name: 'Bar' } ]; + + // bad + users.forEach((user, index) => { + user.id = index; + }); + + // good + const usersWithId = users.map((user, index) => { + return Object.assign({}, user, { id: index }); + }); + ``` #### Parse Strings into Numbers -1. `parseInt()` is preferable over `Number()` or `+` - ```javascript - // bad - +'10' // 10 - // good - Number('10') // 10 +1. `parseInt()` is preferable over `Number()` or `+` - // better - parseInt('10', 10); - ``` + ```javascript + // bad + +'10' // 10 + + // good + Number('10') // 10 + + // better + parseInt('10', 10); + ``` #### CSS classes used for JavaScript + 1. If the class is being used in Javascript it needs to be prepend with `js-` - ```html - // bad - - // good - - ``` + ```html + // bad + + + // good + + ``` ### Vue.js @@ -292,197 +306,211 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. The service has it's own file 1. The store has it's own file 1. Use a function in the bundle file to instantiate the Vue component: - ```javascript - // bad - class { - init() { - new Component({}) - } - } - // good - document.addEventListener('DOMContentLoaded', () => new Vue({ - el: '#element', - components: { - componentName - }, - render: createElement => createElement('component-name'), - })); - ``` + ```javascript + // bad + class { + init() { + new Component({}) + } + } + + // good + document.addEventListener('DOMContentLoaded', () => new Vue({ + el: '#element', + components: { + componentName + }, + render: createElement => createElement('component-name'), + })); + ``` 1. Do not use a singleton for the service or the store - ```javascript - // bad - class Store { - constructor() { - if (!this.prototype.singleton) { - // do something + + ```javascript + // bad + class Store { + constructor() { + if (!this.prototype.singleton) { + // do something + } } } - } - - // good - class Store { - constructor() { - // do something + + // good + class Store { + constructor() { + // do something + } } - } - ``` + ``` 1. Use `.vue` for Vue templates. Do not use `%template` in HAML. #### Naming 1. **Extensions**: Use `.vue` extension for Vue components. Do not use `.js` as file extension ([#34371]). 1. **Reference Naming**: Use PascalCase for their instances: - ```javascript - // bad - import cardBoard from 'cardBoard.vue' - components: { - cardBoard, - }; - - // good - import CardBoard from 'cardBoard.vue' - - components: { - CardBoard, - }; - ``` + ```javascript + // bad + import cardBoard from 'cardBoard.vue' + + components: { + cardBoard, + }; + + // good + import CardBoard from 'cardBoard.vue' + + components: { + CardBoard, + }; + ``` 1. **Props Naming:** Avoid using DOM component prop names. 1. **Props Naming:** Use kebab-case instead of camelCase to provide props in templates. - ```javascript - // bad - - - // good - - // bad - - - // good - - ``` + ```javascript + // bad + + + // good + + + // bad + + + // good + + ``` [#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371 #### Alignment 1. Follow these alignment styles for the template method: - 1. With more than one attribute, all attributes should be on a new line: - ```javascript - // bad - - - - - // good - - - - ``` - 1. The tag can be inline if there is only one attribute: - ```javascript - // good - - - // good - - // bad - - ``` + 1. With more than one attribute, all attributes should be on a new line: + + ```javascript + // bad + + + + + // good + + + + ``` + + 1. The tag can be inline if there is only one attribute: + + ```javascript + // good + + + // good + + + // bad + + ``` #### Quotes + 1. Always use double quotes `"` inside templates and single quotes `'` for all other JS. - ```javascript - // bad - template: ` - - ` - // good - template: ` - - ` - ``` + ```javascript + // bad + template: ` + + ` + + // good + template: ` + + ` + ``` #### Props -1. Props should be declared as an object - ```javascript - // bad - props: ['foo'] - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' +1. Props should be declared as an object + ```javascript + // bad + props: ['foo'] + + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' + } } - } - ``` + ``` 1. Required key should always be provided when declaring a prop - ```javascript - // bad - props: { - foo: { - type: String, - } - } - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' + ```javascript + // bad + props: { + foo: { + type: String, + } } - } - ``` + + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' + } + } + ``` 1. Default key should be provided if the prop is not required. _Note:_ There are some scenarios where we need to check for the existence of the property. On those a default key should not be provided. - ```javascript - // good - props: { - foo: { - type: String, - required: false, - } - } - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' + ```javascript + // good + props: { + foo: { + type: String, + required: false, + } } - } - - // good - props: { - foo: { - type: String, - required: true + + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' + } } - } - ``` + + // good + props: { + foo: { + type: String, + required: true + } + } + ``` #### Data + 1. `data` method should always be a function ```javascript @@ -502,38 +530,41 @@ On those a default key should not be provided. #### Directives 1. Shorthand `@` is preferable over `v-on` - ```javascript - // bad - - - // good - - ``` + ```javascript + // bad + + + // good + + ``` 1. Shorthand `:` is preferable over `v-bind` - ```javascript - // bad - - - // good - - ``` + ```javascript + // bad + + + // good + + ``` #### Closing tags + 1. Prefer self closing component tags - ```javascript - // bad - - // good - - ``` + ```javascript + // bad + + + // good + + ``` #### Ordering 1. Tag order in `.vue` file + ```