diff options
Diffstat (limited to 'doc/development')
30 files changed, 180 insertions, 179 deletions
diff --git a/doc/development/adding_database_indexes.md b/doc/development/adding_database_indexes.md index d1d2b8c4907..c47ce0f1182 100644 --- a/doc/development/adding_database_indexes.md +++ b/doc/development/adding_database_indexes.md @@ -113,9 +113,9 @@ the meaning of the various columns can be found at Because the output of this query relies on the actual usage of your database it may be affected by factors such as (but not limited to): -* Certain queries never being executed, thus not being able to use certain +- Certain queries never being executed, thus not being able to use certain indexes. -* Certain tables having little data, resulting in PostgreSQL using sequence +- Certain tables having little data, resulting in PostgreSQL using sequence scans instead of index scans. In other words, this data is only reliable for a frequently used database with diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index dd4a9e058d7..642dac614c7 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -25,9 +25,9 @@ should only be used for data migrations. Some examples where background migrations can be useful: -* Migrating events from one table to multiple separate tables. -* Populating one column based on JSON stored in another column. -* Migrating data that depends on the output of external services (e.g. an API). +- Migrating events from one table to multiple separate tables. +- Populating one column based on JSON stored in another column. +- Migrating data that depends on the output of external services (e.g. an API). ## Isolation diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 9dffca5b99c..7ac846e4c4d 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -97,28 +97,28 @@ When your code contains more than 500 changes, any major breaking changes, or an This [documentation](issue_workflow.md) outlines the current issue process. -* [Type labels](issue_workflow.md#type-labels) -* [Subject labels](issue_workflow.md#subject-labels) -* [Team labels](issue_workflow.md#team-labels) -* [Release Scoping labels](issue_workflow.md#release-scoping-labels) -* [Priority labels](issue_workflow.md#priority-labels) -* [Severity labels](issue_workflow.md#severity-labels) -* [Label for community contributors](issue_workflow.md#label-for-community-contributors) -* [Issue triaging](issue_workflow.md#issue-triaging) -* [Feature proposals](issue_workflow.md#feature-proposals) -* [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines) -* [Issue weight](issue_workflow.md#issue-weight) -* [Regression issues](issue_workflow.md#regression-issues) -* [Technical and UX debt](issue_workflow.md#technical-and-ux-debt) -* [Stewardship](issue_workflow.md#stewardship) +- [Type labels](issue_workflow.md#type-labels) +- [Subject labels](issue_workflow.md#subject-labels) +- [Team labels](issue_workflow.md#team-labels) +- [Release Scoping labels](issue_workflow.md#release-scoping-labels) +- [Priority labels](issue_workflow.md#priority-labels) +- [Severity labels](issue_workflow.md#severity-labels) +- [Label for community contributors](issue_workflow.md#label-for-community-contributors) +- [Issue triaging](issue_workflow.md#issue-triaging) +- [Feature proposals](issue_workflow.md#feature-proposals) +- [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines) +- [Issue weight](issue_workflow.md#issue-weight) +- [Regression issues](issue_workflow.md#regression-issues) +- [Technical and UX debt](issue_workflow.md#technical-and-ux-debt) +- [Stewardship](issue_workflow.md#stewardship) ## Merge requests This [documentation](merge_request_workflow.md) outlines the current merge request process. -* [Merge request guidelines](merge_request_workflow.md#merge-request-guidelines) -* [Contribution acceptance criteria](merge_request_workflow.md#contribution-acceptance-criteria) -* [Definition of done](merge_request_workflow.md#definition-of-done) +- [Merge request guidelines](merge_request_workflow.md#merge-request-guidelines) +- [Contribution acceptance criteria](merge_request_workflow.md#contribution-acceptance-criteria) +- [Definition of done](merge_request_workflow.md#definition-of-done) ## Style guides diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md index 0e9126ee667..52462a4bec9 100644 --- a/doc/development/fe_guide/components.md +++ b/doc/development/fe_guide/components.md @@ -1,18 +1,19 @@ # Components ## Contents -* [Dropdowns](#dropdowns) -* [Modals](#modals) + +- [Dropdowns](#dropdowns) +- [Modals](#modals) ## Dropdowns See also the [corresponding UX guide](https://design.gitlab.com/#/components/dropdowns). ### How to style a bootstrap dropdown + 1. Use the HTML structure provided by the [docs][bootstrap-dropdowns] 1. Add a specific class to the top level `.dropdown` element - ```Haml .dropdown.my-dropdown %button{ type: 'button', data: { toggle: 'dropdown' }, 'aria-haspopup': true, 'aria-expanded': false } diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md index ce96a9fc8ae..e6aa0be671f 100644 --- a/doc/development/fe_guide/droplab/droplab.md +++ b/doc/development/fe_guide/droplab/droplab.md @@ -177,28 +177,28 @@ droplab.init().addData('trigger', [{ DropLab adds some CSS classes to help lower the barrier to integration. -For example, +For example: -* The `droplab-item-selected` css class is added to items that have been selected -either by a mouse click or by enter key selection. -* The `droplab-item-active` css class is added to items that have been selected -using arrow key navigation. -* You can add the `droplab-item-ignore` css class to any item that you do not want to be selectable. For example, -an `<li class="divider"></li>` list divider element that should not be interactive. +- The `droplab-item-selected` css class is added to items that have been selected + either by a mouse click or by enter key selection. +- The `droplab-item-active` css class is added to items that have been selected + using arrow key navigation. +- You can add the `droplab-item-ignore` css class to any item that you do not want to be selectable. For example, + an `<li class="divider"></li>` list divider element that should not be interactive. ## Internal events DropLab uses some custom events to help lower the barrier to integration. -For example, +For example: -* The `click.dl` event is fired when an `li` list item has been clicked. It is also -fired when a list item has been selected with the keyboard. It is also fired when a -`HookButton` button is clicked (a registered `button` tag or `a` tag trigger). -* The `input.dl` event is fired when a `HookInput` (a registered `input` tag trigger) triggers an `input` event. -* The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` event. -* The `keyup.dl` event is fired when a `HookInput` triggers a `keyup` event. -* The `keydown.dl` event is fired when a `HookInput` triggers a `keydown` event. +- The `click.dl` event is fired when an `li` list item has been clicked. It is also + fired when a list item has been selected with the keyboard. It is also fired when a + `HookButton` button is clicked (a registered `button` tag or `a` tag trigger). +- The `input.dl` event is fired when a `HookInput` (a registered `input` tag trigger) triggers an `input` event. +- The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` event. +- The `keyup.dl` event is fired when a `HookInput` triggers a `keyup` event. +- The `keydown.dl` event is fired when a `HookInput` triggers a `keydown` event. These custom events add a `detail` object to the vanilla `Event` object that provides some potentially useful data. @@ -233,9 +233,9 @@ droplab.init(trigger, list, [droplabAjax], { ### Documentation -* [Ajax plugin](plugins/ajax.md) -* [Filter plugin](plugins/filter.md) -* [InputSetter plugin](plugins/input_setter.md) +- [Ajax plugin](plugins/ajax.md) +- [Filter plugin](plugins/filter.md) +- [InputSetter plugin](plugins/input_setter.md) ### Development diff --git a/doc/development/fe_guide/droplab/plugins/ajax.md b/doc/development/fe_guide/droplab/plugins/ajax.md index 9c7e56fa448..b6a883ce6c4 100644 --- a/doc/development/fe_guide/droplab/plugins/ajax.md +++ b/doc/development/fe_guide/droplab/plugins/ajax.md @@ -8,10 +8,10 @@ Add the `Ajax` object to the plugins array of a `DropLab.prototype.init` or `Dro `Ajax` requires 2 config values, the `endpoint` and `method`. -* `endpoint` should be a URL to the request endpoint. -* `method` should be `setData` or `addData`. -* `setData` completely replaces the dropdown with the response data. -* `addData` appends the response data to the current dropdown list. +- `endpoint` should be a URL to the request endpoint. +- `method` should be `setData` or `addData`. +- `setData` completely replaces the dropdown with the response data. +- `addData` appends the response data to the current dropdown list. ```html <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> diff --git a/doc/development/fe_guide/droplab/plugins/filter.md b/doc/development/fe_guide/droplab/plugins/filter.md index 0853ea4d320..ddc6a3386c7 100644 --- a/doc/development/fe_guide/droplab/plugins/filter.md +++ b/doc/development/fe_guide/droplab/plugins/filter.md @@ -7,8 +7,8 @@ to the dropdown using a simple fuzzy string search of an input value. Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. -* `Filter` requires a config value for `template`. -* `template` should be the key of the objects within your data array that you want to compare +- `Filter` requires a config value for `template`. +- `template` should be the key of the objects within your data array that you want to compare to the user input string, for filtering. ```html diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md index 94f3c8254a8..8e28a41f32e 100644 --- a/doc/development/fe_guide/droplab/plugins/input_setter.md +++ b/doc/development/fe_guide/droplab/plugins/input_setter.md @@ -6,9 +6,9 @@ Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. -* `InputSetter` requires a config value for `input` and `valueAttribute`. -* `input` should be the DOM element that you want to manipulate. -* `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value +- `InputSetter` requires a config value for `input` and `valueAttribute`. +- `input` should be the DOM element that you want to manipulate. +- `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value to update the `input` element with. You can also set the `InputSetter` config to an array of objects, which will allow you to update multiple elements. diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index cca3ad6fae6..ad87ecf1b87 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -118,7 +118,7 @@ The [externalization part of the guide](../i18n/externalization.md) explains the ## [DropLab](droplab/droplab.md) Our internal `DropLab` dropdown library. -* [DropLab](droplab/droplab.md) -* [Ajax plugin](droplab/plugins/ajax.md) -* [Filter plugin](droplab/plugins/filter.md) -* [InputSetter plugin](droplab/plugins/input_setter.md) +- [DropLab](droplab/droplab.md) +- [Ajax plugin](droplab/plugins/ajax.md) +- [Filter plugin](droplab/plugins/filter.md) +- [InputSetter plugin](droplab/plugins/input_setter.md) diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index ef0eed786d2..e5a383c25f5 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -29,8 +29,8 @@ To improve the time to first render we are using lazy loading for images. This w the actual image source on the `data-src` attribute. After the HTML is rendered and JavaScript is loaded, the value of `data-src` will be moved to `src` automatically if the image is in the current viewport. -* Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` AND adding the class `lazy` -* If you are using the Rails `image_tag` helper, all images will be lazy-loaded by default unless `lazy: false` is provided. +- Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` AND adding the class `lazy`. +- If you are using the Rails `image_tag` helper, all images will be lazy-loaded by default unless `lazy: false` is provided. If you are asynchronously adding content which contains lazy images then you need to call the function `gl.lazyLoader.searchLazyImages()` which will search for lazy images and load them if needed. diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index 6e014e8c751..b90dc90e424 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -4,15 +4,15 @@ We use the [CarrierWave] gem to handle file upload, store and retrieval. There are many places where file uploading is used, according to contexts: -* System +- System - Instance Logo (logo visible in sign in/sign up pages) - Header Logo (one displayed in the navigation bar) -* Group +- Group - Group avatars -* User +- User - User avatars - User snippet attachments -* Project +- Project - Project avatars - Issues/MR/Notes Markdown attachments - Issues/MR/Notes Legacy Markdown attachments @@ -52,7 +52,7 @@ hash of the project ID instead, if project migrates to the new approach (introdu ### Path segments -Files are stored at multiple locations and use different path schemes. +Files are stored at multiple locations and use different path schemes. All the `GitlabUploader` derived classes should comply with this path segment schema: ``` @@ -61,7 +61,7 @@ All the `GitlabUploader` derived classes should comply with this path segment sc | `<gitlab_root>/public/` | `uploads/-/system/` | `user/avatar/:id/` | `:filename` | | ----------------------- + ------------------------- + --------------------------------- + -------------------------------- | | `CarrierWave.root` | `GitlabUploader.base_dir` | `GitlabUploader#dynamic_segment` | `CarrierWave::Uploader#filename` | -| | `CarrierWave::Uploader#store_dir` | | +| | `CarrierWave::Uploader#store_dir` | | | FileUploader | ----------------------- + ------------------------- + --------------------------------- + -------------------------------- | @@ -69,7 +69,7 @@ All the `GitlabUploader` derived classes should comply with this path segment sc | `<gitlab_root>/shared/` | `snippets/` | `:secret/` | `:filename` | | ----------------------- + ------------------------- + --------------------------------- + -------------------------------- | | `CarrierWave.root` | `GitlabUploader.base_dir` | `GitlabUploader#dynamic_segment` | `CarrierWave::Uploader#filename` | -| | `CarrierWave::Uploader#store_dir` | | +| | `CarrierWave::Uploader#store_dir` | | | | | `FileUploader#upload_path | | ObjectStore::Concern (store = remote) @@ -77,7 +77,7 @@ All the `GitlabUploader` derived classes should comply with this path segment sc | `<bucket_name>` | <ignored> | `user/avatar/:id/` | `:filename` | | ----------------------- + ------------------------- + ----------------------------------- + -------------------------------- | | `#fog_dir` | `GitlabUploader.base_dir` | `GitlabUploader#dynamic_segment` | `CarrierWave::Uploader#filename` | -| | | `ObjectStorage::Concern#store_dir` | | +| | | `ObjectStorage::Concern#store_dir` | | | | | `ObjectStorage::Concern#upload_path | ``` diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index 863ac049db6..5445f36b9fa 100644 --- a/doc/development/github_importer.md +++ b/doc/development/github_importer.md @@ -13,20 +13,20 @@ or Rake tasks. The parallel importer on the other hand uses Sidekiq. ## Requirements -* GitLab CE 10.2.0 or newer. -* Sidekiq workers that process the `github_importer` and +- GitLab CE 10.2.0 or newer. +- Sidekiq workers that process the `github_importer` and `github_importer_advance_stage` queues (this is enabled by default). -* Octokit (used for interacting with the GitHub API) +- Octokit (used for interacting with the GitHub API). ## Code structure The importer's codebase is broken up into the following directories: -* `lib/gitlab/github_import`: this directory contains most of the code such as +- `lib/gitlab/github_import`: this directory contains most of the code such as the classes used for importing resources. -* `app/workers/gitlab/github_import`: this directory contains the Sidekiq +- `app/workers/gitlab/github_import`: this directory contains the Sidekiq workers. -* `app/workers/concerns/gitlab/github_import`: this directory contains a few +- `app/workers/concerns/gitlab/github_import`: this directory contains a few modules reused by the various Sidekiq workers. ## Architecture overview @@ -188,8 +188,8 @@ projects get imported the fewer GitHub API calls will be needed. The code for this resides in: -* `lib/gitlab/github_import/user_finder.rb` -* `lib/gitlab/github_import/caching.rb` +- `lib/gitlab/github_import/user_finder.rb` +- `lib/gitlab/github_import/caching.rb` ## Mapping labels and milestones @@ -204,6 +204,6 @@ project that is being imported. The code for this resides in: -* `lib/gitlab/github_import/label_finder.rb` -* `lib/gitlab/github_import/milestone_finder.rb` -* `lib/gitlab/github_import/caching.rb` +- `lib/gitlab/github_import/label_finder.rb` +- `lib/gitlab/github_import/milestone_finder.rb` +- `lib/gitlab/github_import/caching.rb` diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index a5a34d82bec..1b9ebb50c29 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -96,8 +96,8 @@ end ### Why -* Because it is not isolated therefore it might be broken at times. -* Because it doesn't work whenever the method we want to stub was defined +- Because it is not isolated therefore it might be broken at times. +- Because it doesn't work whenever the method we want to stub was defined in a prepended module, which is very likely the case in EE. We could see error like this: diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index a36dc6424a7..5f95cf3707c 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -11,12 +11,12 @@ Instrumenting methods is done by using the `Gitlab::Metrics::Instrumentation` module. This module offers a few different methods that can be used to instrument code: -* `instrument_method`: instruments a single class method. -* `instrument_instance_method`: instruments a single instance method. -* `instrument_class_hierarchy`: given a Class this method will recursively +- `instrument_method`: instruments a single class method. +- `instrument_instance_method`: instruments a single instance method. +- `instrument_class_hierarchy`: given a Class this method will recursively instrument all sub-classes (both class and instance methods). -* `instrument_methods`: instruments all public and private class methods of a Module. -* `instrument_instance_methods`: instruments all public and private instance methods of a +- `instrument_methods`: instruments all public and private class methods of a Module. +- `instrument_instance_methods`: instruments all public and private instance methods of a Module. To remove the need for typing the full `Gitlab::Metrics::Instrumentation` diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index ee01c89e0ed..6f1baad3a2d 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -9,8 +9,8 @@ To measure the impact of a merge request you can use [Sherlock](profiling.md#sherlock). It's also highly recommended that you read the following guides: -* [Performance Guidelines](performance.md) -* [What requires downtime?](what_requires_downtime.md) +- [Performance Guidelines](performance.md) +- [What requires downtime?](what_requires_downtime.md) ## Impact Analysis diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 23aa318ef91..98b54684d39 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -40,7 +40,7 @@ migrations _unless_ schema changes are absolutely required to solve a problem. ## What Requires Downtime? The document ["What Requires Downtime?"](what_requires_downtime.md) specifies -various database operations, such as +various database operations, such as - [adding, dropping, and renaming columns](what_requires_downtime.md#adding-columns) - [changing column constraints and types](what_requires_downtime.md#changing-column-constraints) @@ -59,9 +59,9 @@ the migrations that _do_ require downtime. To tag a migration, add the following two constants to the migration class' body: -* `DOWNTIME`: a boolean that when set to `true` indicates the migration requires +- `DOWNTIME`: a boolean that when set to `true` indicates the migration requires downtime. -* `DOWNTIME_REASON`: a String containing the reason for the migration requiring +- `DOWNTIME_REASON`: a String containing the reason for the migration requiring downtime. This constant **must** be set when `DOWNTIME` is set to `true`. For example: @@ -318,8 +318,8 @@ end Instead of using these methods one should use the following methods to store timestamps with timezones: -* `add_timestamps_with_timezone` -* `timestamps_with_timezone` +- `add_timestamps_with_timezone` +- `timestamps_with_timezone` This ensures all timestamps have a time zone specified. This in turn means existing timestamps won't suddenly use a different timezone when the system's timezone changes. It also makes it very clear which diff --git a/doc/development/new_fe_guide/development/components.md b/doc/development/new_fe_guide/development/components.md index 899efb398cd..8ae58d30c35 100644 --- a/doc/development/new_fe_guide/development/components.md +++ b/doc/development/new_fe_guide/development/components.md @@ -6,16 +6,16 @@ We have a lot of graphing libraries in our codebase to render graphs. In an effo We chose D3 as our library going forward because of the following features: -* [Tree shaking webpack capabilities.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40) -* [Compatible with vue.js as well as vanilla javascript.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40) +- [Tree shaking webpack capabilities](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40). +- [Compatible with vue.js as well as vanilla javascript](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40). D3 is very popular across many projects outside of GitLab: -* [The New York Times](https://archive.nytimes.com/www.nytimes.com/interactive/2012/02/13/us/politics/2013-budget-proposal-graphic.html) -* [plot.ly](https://plot.ly/) -* [Droptask](https://www.droptask.com/) +- [The New York Times](https://archive.nytimes.com/www.nytimes.com/interactive/2012/02/13/us/politics/2013-budget-proposal-graphic.html) +- [plot.ly](https://plot.ly/) +- [Droptask](https://www.droptask.com/) Within GitLab, D3 has been used for the following notable features -* [Prometheus graphs](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html) -* Contribution calendars +- [Prometheus graphs](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html) +- Contribution calendars diff --git a/doc/development/new_fe_guide/development/performance.md b/doc/development/new_fe_guide/development/performance.md index 5ccd5357314..640a8d64176 100644 --- a/doc/development/new_fe_guide/development/performance.md +++ b/doc/development/new_fe_guide/development/performance.md @@ -7,10 +7,10 @@ We have a performance dashboard available in one of our [grafana instances](http These pages can be found inside a text file in the gitlab-build-images [repository](https://gitlab.com/gitlab-org/gitlab-build-images) called [gitlab.txt](https://gitlab.com/gitlab-org/gitlab-build-images/blob/master/scripts/gitlab.txt) Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing urls of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/team) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes will go live on the next scheduled run after the changes are merged into `master`. -There are 3 recommended high impact metrics to review on each page +There are 3 recommended high impact metrics to review on each page: -* [First visual change](https://developers.google.com/web/tools/lighthouse/audits/first-meaningful-paint) -* [Speed Index](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) -* [Visual Complete 95%](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) +- [First visual change](https://developers.google.com/web/tools/lighthouse/audits/first-meaningful-paint) +- [Speed Index](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) +- [Visual Complete 95%](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) For these metrics, lower numbers are better as it means that the website is more performant. diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md index 0d98180add0..310640f0a01 100644 --- a/doc/development/new_fe_guide/development/testing.md +++ b/doc/development/new_fe_guide/development/testing.md @@ -20,8 +20,8 @@ These have been removed from our codebase in May 2018 ([#23036](https://gitlab.c See also: -- [old testing guide](../../testing_guide/frontend_testing.html) -- [notes on testing Vue components](../../fe_guide/vue.html#testing-vue-components) +- [Old testing guide](../../testing_guide/frontend_testing.html). +- [Notes on testing Vue components](../../fe_guide/vue.html#testing-vue-components). [#53757]: https://gitlab.com/gitlab-org/gitlab-ce/issues/53757 @@ -302,8 +302,8 @@ Check an example in [spec/javascripts/ide/stores/actions_spec.jsspec/javascripts To make mounting a Vue component easier and more readable, we have a few helpers available in `spec/helpers/vue_mount_component_helper`. -* `createComponentWithStore` -* `mountComponentWithStore` +- `createComponentWithStore` +- `mountComponentWithStore` Examples of usage: diff --git a/doc/development/new_fe_guide/modules/index.md b/doc/development/new_fe_guide/modules/index.md index 0a7f2dbd819..a7820442df0 100644 --- a/doc/development/new_fe_guide/modules/index.md +++ b/doc/development/new_fe_guide/modules/index.md @@ -1,5 +1,5 @@ # Modules -* [DirtySubmit](dirty_submit.md) +- [DirtySubmit](dirty_submit.md) - Disable form submits until there are unsaved changes.
\ No newline at end of file + Disable form submits until there are unsaved changes. diff --git a/doc/development/performance.md b/doc/development/performance.md index 4cc2fdc9a58..972c93be817 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -23,9 +23,9 @@ The process of solving performance problems is roughly as follows: When providing timings make sure to provide: -* The 95th percentile -* The 99th percentile -* The mean +- The 95th percentile +- The 99th percentile +- The mean When providing screenshots of graphs, make sure that both the X and Y axes and the legend are clearly visible. If you happen to have access to GitLab.com's own @@ -36,12 +36,12 @@ graphs/dashboards. GitLab provides built-in tools to help improve performance and availability: -* [Profiling](profiling.md) - * [Sherlock](profiling.md#sherlock) -* [GitLab Performance Monitoring](../administration/monitoring/performance/index.md) -* [Request Profiling](../administration/monitoring/performance/request_profiling.md) -* [QueryRecoder](query_recorder.md) for preventing `N+1` regressions -* [Chaos endpoints](chaos_endpoints.md) for testing failure scenarios. Intended mainly for testing availability. +- [Profiling](profiling.md). + - [Sherlock](profiling.md#sherlock). +- [GitLab Performance Monitoring](../administration/monitoring/performance/index.md). +- [Request Profiling](../administration/monitoring/performance/request_profiling.md). +- [QueryRecoder](query_recorder.md) for preventing `N+1` regressions. +- [Chaos endpoints](chaos_endpoints.md) for testing failure scenarios. Intended mainly for testing availability. GitLab employees can use GitLab.com's performance monitoring systems located at <https://dashboards.gitlab.net>, this requires you to log in using your @@ -269,11 +269,11 @@ piece of code is worth optimizing. The only two things you can do are: Some examples of changes that aren't really important/worth the effort: -* Replacing double quotes with single quotes. -* Replacing usage of Array with Set when the list of values is very small. -* Replacing library A with library B when both only take up 0.1% of the total +- Replacing double quotes with single quotes. +- Replacing usage of Array with Set when the list of values is very small. +- Replacing library A with library B when both only take up 0.1% of the total execution time. -* Calling `freeze` on every string (see [String Freezing](#string-freezing)). +- Calling `freeze` on every string (see [String Freezing](#string-freezing)). ## Slow Operations & Sidekiq diff --git a/doc/development/policies.md b/doc/development/policies.md index 62141356f59..97424d90fb5 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -13,7 +13,7 @@ Permissions are broken into two parts: `conditions` and `rules`. Conditions are Conditions are defined by the `condition` method, and are given a name and a block. The block will be executed in the context of the policy object - so it can access `@user` and `@subject`, as well as call any methods defined on the policy. Note that `@user` may be nil (in the anonymous case), but `@subject` is guaranteed to be a real instance of the subject class. -``` ruby +```ruby class FooPolicy < BasePolicy condition(:is_public) do # @subject guaranteed to be an instance of Foo @@ -37,7 +37,7 @@ Conditions are cached according to their scope. Scope and ordering will be cover A `rule` is a logical combination of conditions and other rules, that are configured to enable or prevent certain abilities. It is important to note that the rule configuration is static - a rule's logic cannot touch the database or know about `@user` or `@subject`. This allows us to cache only at the condition level. Rules are specified through the `rule` method, which takes a block of DSL configuration, and returns an object that responds to `#enable` or `#prevent`: -``` ruby +```ruby class FooPolicy < BasePolicy # ... @@ -57,10 +57,10 @@ end Within the rule DSL, you can use: -* A regular word mentions a condition by name - a rule that is in effect when that condition is truthy. -* `~` indicates negation -* `&` and `|` are logical combinations, also available as `all?(...)` and `any?(...)` -* `can?(:other_ability)` delegates to the rules that apply to `:other_ability`. Note that this is distinct from the instance method `can?`, which can check dynamically - this only configures a delegation to another ability. +- A regular word mentions a condition by name - a rule that is in effect when that condition is truthy. +- `~` indicates negation. +- `&` and `|` are logical combinations, also available as `all?(...)` and `any?(...)`. +- `can?(:other_ability)` delegates to the rules that apply to `:other_ability`. Note that this is distinct from the instance method `can?`, which can check dynamically - this only configures a delegation to another ability. ## Scores, Order, Performance @@ -72,7 +72,7 @@ When a policy is asked whether a particular ability is allowed (`policy.allowed? Sometimes, a condition will only use data from `@user` or only from `@subject`. In this case, we want to change the scope of the caching, so that we don't recalculate conditions unnecessarily. For example, given: -``` ruby +```ruby class FooPolicy < BasePolicy condition(:expensive_condition) { @subject.expensive_query? } @@ -82,7 +82,7 @@ end Naively, if we call `Ability.can?(user1, :some_ability, foo)` and `Ability.can?(user2, :some_ability, foo)`, we would have to calculate the condition twice - since they are for different users. But if we use the `scope: :subject` option: -``` ruby +```ruby condition(:expensive_condition, scope: :subject) { @subject.expensive_query? } ``` @@ -93,7 +93,7 @@ both user and subject (including a simple anonymous check!) your result will be Sometimes we are checking permissions for a lot of users for one subject, or a lot of subjects for one user. In this case, we want to set a *preferred scope* - i.e. tell the system that we prefer rules that can be cached on the repeated parameter. For example, in `Ability.users_that_can_read_project`: -``` ruby +```ruby def users_that_can_read_project(users, project) DeclarativePolicy.subject_scope do users.select { |u| allowed?(u, :read_project, project) } @@ -105,9 +105,9 @@ This will, for example, prefer checking `project.public?` to checking `user.admi ## Delegation -Delegation is the inclusion of rules from another policy, on a different subject. For example, +Delegation is the inclusion of rules from another policy, on a different subject. For example: -``` ruby +```ruby class FooPolicy < BasePolicy delegate { @subject.project } end diff --git a/doc/development/polymorphic_associations.md b/doc/development/polymorphic_associations.md index d63b9fb115f..5d69c8add38 100644 --- a/doc/development/polymorphic_associations.md +++ b/doc/development/polymorphic_associations.md @@ -7,9 +7,9 @@ usually works by adding two columns to a table: a target type column, and a target id. For example, at the time of writing we have such a setup for `members` with the following columns: -* `source_type`: a string defining the model to use, can be either `Project` or +- `source_type`: a string defining the model to use, can be either `Project` or `Namespace`. -* `source_id`: the ID of the row to retrieve based on `source_type`. For +- `source_id`: the ID of the row to retrieve based on `source_type`. For example, when `source_type` is `Project` then `source_id` will contain a project ID. @@ -92,10 +92,10 @@ AND source_id = 4 Instead such a table should be broken up into separate tables. For example, you may end up with 4 tables in this case: -* project_members -* group_members -* pending_project_members -* pending_group_members +- project_members +- group_members +- pending_project_members +- pending_group_members This makes querying data trivial. For example, to get the members of a group you'd run: diff --git a/doc/development/post_deployment_migrations.md b/doc/development/post_deployment_migrations.md index 5986efa9974..a41096aa3eb 100644 --- a/doc/development/post_deployment_migrations.md +++ b/doc/development/post_deployment_migrations.md @@ -70,6 +70,6 @@ version (which doesn't depend on the column anymore) has been deployed. Some other examples where these migrations are useful: -* Cleaning up data generated due to a bug in GitLab -* Removing tables -* Migrating jobs from one Sidekiq queue to another +- Cleaning up data generated due to a bug in GitLab +- Removing tables +- Migrating jobs from one Sidekiq queue to another diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index 83d7d42bd1f..01cedf734fb 100644 --- a/doc/development/reusing_abstractions.md +++ b/doc/development/reusing_abstractions.md @@ -149,11 +149,11 @@ typically in JSON. These are class methods defined by _GitLab itself_, including the following methods provided by Active Record: -* `find` -* `find_by_id` -* `delete_all` -* `destroy` -* `destroy_all` +- `find` +- `find_by_id` +- `delete_all` +- `destroy` +- `destroy_all` Any other methods such as `find_by(some_column: X)` are not included, and instead fall under the "Active Record" abstraction. @@ -163,10 +163,10 @@ instead fall under the "Active Record" abstraction. Instance methods defined on Active Record models by _GitLab itself_. Methods provided by Active Record are not included, except for the following methods: -* `save` -* `update` -* `destroy` -* `delete` +- `save` +- `update` +- `destroy` +- `delete` ### Active Record diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md index b65fbc9d958..ef1aba95712 100644 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -10,12 +10,12 @@ disable those changes, without having to revert an entire release. Starting with GitLab 11.4, developers are required to use feature flags for non-trivial changes. Such changes include: -* New features (e.g. a new merge request widget, epics, etc). -* Complex performance improvements that may require additional testing in +- New features (e.g. a new merge request widget, epics, etc). +- Complex performance improvements that may require additional testing in production, such as rewriting complex queries. -* Invasive changes to the user interface, such as a new navigation bar or the +- Invasive changes to the user interface, such as a new navigation bar or the removal of a sidebar. -* Adding support for importing projects from a third-party service. +- Adding support for importing projects from a third-party service. In all cases, those working on the changes can best decide if a feature flag is necessary. For example, changing the color of a button doesn't need a feature diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index f8993653aec..6012f1080ab 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -185,8 +185,8 @@ See this [section][vue-test]. `rake karma` runs the frontend-only (JavaScript) tests. It consists of two subtasks: -* `rake karma:fixtures` (re-)generates fixtures -* `rake karma:tests` actually executes the tests +- `rake karma:fixtures` (re-)generates fixtures +- `rake karma:tests` actually executes the tests As long as the fixtures don't change, `rake karma:tests` (or `yarn karma`) is sufficient (and saves you some time). @@ -243,14 +243,14 @@ supported by the PhantomJS test runner which is used for both Karma and RSpec tests. We polyfill some JavaScript objects for older browsers, but some features are still unavailable: -* Array.from -* Array.first -* Async functions -* Generators -* Array destructuring -* For..Of -* Symbol/Symbol.iterator -* Spread +- Array.from +- Array.first +- Async functions +- Generators +- Array destructuring +- For..Of +- Symbol/Symbol.iterator +- Spread Until these are polyfilled appropriately, they should not be used. Please update this list with additional unsupported features. diff --git a/doc/development/understanding_explain_plans.md b/doc/development/understanding_explain_plans.md index adf8795a5e3..01a0044f096 100644 --- a/doc/development/understanding_explain_plans.md +++ b/doc/development/understanding_explain_plans.md @@ -625,9 +625,9 @@ This is a bit of a difficult question to answer, because the definition of "bad" is relative to the problem you are trying to solve. However, some patterns are best avoided in most cases, such as: -* Sequential scans on large tables -* Filters that remove a lot of rows -* Performing a certain step (e.g. an index scan) that requires _a lot_ of +- Sequential scans on large tables +- Filters that remove a lot of rows +- Performing a certain step (e.g. an index scan) that requires _a lot_ of buffers (e.g. more than 512 MB for GitLab.com). As a general guideline, aim for a query that: @@ -650,8 +650,8 @@ different queries. The only _rule_ is that you _must always measure_ your query (preferably using a production-like database) using `EXPLAIN (ANALYZE, BUFFERS)` and related tools such as: -* <https://explain.depesz.com/> -* <http://tatiyants.com/postgres-query-plan-visualization/> +- <https://explain.depesz.com/> +- <http://tatiyants.com/postgres-query-plan-visualization/> GitLab employees can also use our chatops solution, available in Slack using the `/chatops` slash command. You can use chatops to get a query plan by running the diff --git a/doc/development/utilities.md b/doc/development/utilities.md index e5466ae8914..0e396baccff 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -4,7 +4,7 @@ We developed a number of utilities to ease development. ## [`MergeHash`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/merge_hash.rb) -* Deep merges an array of hashes: +- Deep merges an array of hashes: ``` ruby Gitlab::Utils::MergeHash.merge( @@ -31,7 +31,7 @@ We developed a number of utilities to ease development. ] ``` -* Extracts all keys and values from a hash into an array: +- Extracts all keys and values from a hash into an array: ``` ruby Gitlab::Utils::MergeHash.crush( @@ -47,14 +47,14 @@ We developed a number of utilities to ease development. ## [`Override`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/override.rb) -* This utility could help us check if a particular method would override +- This utility could help us check if a particular method would override another method or not. It has the same idea of Java's `@Override` annotation or Scala's `override` keyword. However we only do this check when `ENV['STATIC_VERIFICATION']` is set to avoid production runtime overhead. This is useful to check: - * If we have typos in overriding methods. - * If we renamed the overridden methods, making original overriding methods + - If we have typos in overriding methods. + - If we renamed the overridden methods, making original overriding methods overrides nothing. Here's a simple example: @@ -92,7 +92,7 @@ We developed a number of utilities to ease development. ## [`StrongMemoize`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/strong_memoize.rb) -* Memoize the value even if it is `nil` or `false`. +- Memoize the value even if it is `nil` or `false`. We often do `@value ||= compute`, however this doesn't work well if `compute` might eventually give `nil` and we don't want to compute again. @@ -126,7 +126,7 @@ We developed a number of utilities to ease development. end ``` -* Clear memoization +- Clear memoization ``` ruby class Find diff --git a/doc/development/verifying_database_capabilities.md b/doc/development/verifying_database_capabilities.md index ffdeff47d4a..661ab9cef1a 100644 --- a/doc/development/verifying_database_capabilities.md +++ b/doc/development/verifying_database_capabilities.md @@ -6,9 +6,9 @@ necessary to add database (version) specific behaviour. To facilitate this we have the following methods that you can use: -* `Gitlab::Database.postgresql?`: returns `true` if PostgreSQL is being used -* `Gitlab::Database.mysql?`: returns `true` if MySQL is being used -* `Gitlab::Database.version`: returns the PostgreSQL version number as a string +- `Gitlab::Database.postgresql?`: returns `true` if PostgreSQL is being used +- `Gitlab::Database.mysql?`: returns `true` if MySQL is being used +- `Gitlab::Database.version`: returns the PostgreSQL version number as a string in the format `X.Y.Z`. This method does not work for MySQL This allows you to write code such as: |