Merge branch 'docs-repo-merge-21-project-merge' into 'master'

Docs: Merge EE doc/user/project/merge_requests to CE See merge request gitlab-org/gitlab-ce!27943

Merge branch 'docs-repo-merge-21-project-merge' into 'master'
Docs: Merge EE doc/user/project/merge_requests to CE See merge request gitlab-org/gitlab-ce!27943
79052662 · Achilleas Pipinellis · 205df512 · 12e19697 · 79052662 · 79052662
Commit 79052662 authored May 05, 2019 by Achilleas Pipinellis
36 changed files
--- a/doc/user/project/merge_requests/browser_performance_testing.md
+++ b/doc/user/project/merge_requests/browser_performance_testing.md
+# Browser Performance Testing **[PREMIUM]**
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3507)
+in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3.
+## Overview
+If your application offers a web interface and you are using
+[GitLab CI/CD](../../../ci/README.md), you can quickly determine the performance
+impact of pending code changes.
+GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source
+tool for measuring the performance of web sites, and has built a simple
+[Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance)
+which outputs the results in a file called `performance.json`. This plugin
+outputs the performance score for each page that is analyzed.
+The [Sitespeed.io performance score](http://examples.sitespeed.io/6.0/2017-11-23-23-43-35/help.html)
+is a composite value based on best practices, and we will be expanding support
+for [additional metrics](https://gitlab.com/gitlab-org/gitlab-ee/issues/4370)
+in a future release.
+Going a step further, GitLab can show the Performance report right
+in the merge request widget area:
+## Use cases
+For instance, consider the following workflow:
+1. A member of the marketing team is attempting to track engagement by adding a new tool
+1. With browser performance metrics, they see how their changes are impacting the usability of the page for end users
+1. The metrics show that after their changes the performance score of the page has gone down
+1. When looking at the detailed report, they see that the new Javascript library was included in `<head>` which affects loading page speed
+1. They ask a front end developer to help them, who sets the library to load asynchronously
+1. The frontend developer approves the merge request and authorizes its deployment to production
+## How it works
+First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the
+[Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance-premium).
+For more information on how the Performance job should look like, check the
+example on [Testing Browser Performance](../../../ci/examples/browser_performance.md).
+GitLab then checks this report, compares key performance metrics for each page
+between the source and target branches, and shows the information right on the merge request.
+>**Note:**
+If the Performance report doesn't have anything to compare to, no information
+will be displayed in the merge request area. That is the case when you add the
+Performance job in your `.gitlab-ci.yml` for the very first time.
+Consecutive merge requests will have something to compare to and the Performance
+report will be shown properly.
+![Performance Widget](img/browser_performance_testing.png)
--- a/doc/user/project/merge_requests/code_quality.md
+++ b/doc/user/project/merge_requests/code_quality.md
+# Code Quality **[STARTER]**
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1984)
+in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3.
+## Overview
+If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your
+source code quality using GitLab Code Quality.
+Code Quality uses [Code Climate Engines](https://codeclimate.com), which are
+free and open source. Code Quality doesn’t require a Code Climate subscription.
+Going a step further, GitLab can show the Code Quality report right
+in the merge request widget area:
+![Code Quality Widget](img/code_quality.gif)
+## Use cases
+For instance, consider the following workflow:
+1. Your backend team member starts a new implementation for making certain feature in your app faster
+1. With Code Quality reports, they analyze how their implementation is impacting the code quality
+1. The metrics show that their code degrade the quality in 10 points
+1. You ask a co-worker to help them with this modification
+1. They both work on the changes until Code Quality report displays no degradations, only improvements
+1. You approve the merge request and authorize its deployment to staging
+1. Once verified, their changes are deployed to production
+## How it works
+First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the
+[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter).
+The Code Quality report artifact is a subset of the
+[Code Climate spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types).
+It must be a JSON file containing an array of objects with the following properties:
+| Name                   | Description                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------- |
+| `description`          | A description of the code quality violation.                                           |
+| `fingerprint`          | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. |
+| `location.path`        | The relative path to the file containing the code quality violation.                   |
+| `location.lines.begin` | The line on which the code quality violation occurred.                                 |
+Example:
+```json
+[
+  {
+    "description": "'unused' is assigned a value but never used.",
+    "fingerprint": "7815696ecbf1c96e6894b779456d330e",
+    "location": {
+      "path": "lib/index.js",
+      "lines": {
+        "begin": 42
+      }
+    }
+  }
+]
+```
+NOTE: **Note:**
+Although the Code Climate spec supports more properties, those are ignored by GitLab.
+For more information on how the Code Quality job should look like, check the
+example on [analyzing a project's code quality](../../../ci/examples/code_quality.md).
+GitLab then checks this report, compares the metrics between the source and target
+branches, and shows the information right on the merge request.
+CAUTION: **Caution:**
+If multiple jobs in a pipeline generate a code quality artifact, only the artifact from
+the last created job (the job with the largest job ID) is used. To avoid confusion,
+configure only one job to generate a code quality artifact.
+NOTE: **Note:**
+If the Code Quality report doesn't have anything to compare to, no information
+will be displayed in the merge request area. That is the case when you add the
+Code Quality job in your `.gitlab-ci.yml` for the very first time.
+Consecutive merge requests will have something to compare to and the Code Quality
+report will be shown properly.
--- a/doc/user/project/merge_requests/code_quality_diff.md
+++ b/doc/user/project/merge_requests/code_quality_diff.md
+---
+redirect_from: 'https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html'
+redirect_to: 'code_quality.md'
+---
+This document was moved to [another location](code_quality.md).
--- a/doc/user/project/merge_requests/container_scanning.md
+++ b/doc/user/project/merge_requests/container_scanning.md
+---
+redirect_to: 'https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html'
+---
+This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html).
--- a/doc/user/project/merge_requests/dast.md
+++ b/doc/user/project/merge_requests/dast.md
+---
+redirect_to: 'https://docs.gitlab.com/ee/user/application_security/dast/index.html'
+---
+This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/dast/index.html).
--- a/doc/user/project/merge_requests/dependency_scanning.md
+++ b/doc/user/project/merge_requests/dependency_scanning.md
+---
+redirect_to: 'https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.html'
+---
+This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.html).
--- a/doc/user/project/merge_requests/img/approvals_can_override.png
+++ b/doc/user/project/merge_requests/img/approvals_can_override.png
--- a/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png
+++ b/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png
--- a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png
+++ b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png
--- a/doc/user/project/merge_requests/img/approvals_remove_on_push.png
+++ b/doc/user/project/merge_requests/img/approvals_remove_on_push.png
--- a/doc/user/project/merge_requests/img/approvals_starter_project_edit.png
+++ b/doc/user/project/merge_requests/img/approvals_starter_project_edit.png
--- a/doc/user/project/merge_requests/img/approvals_starter_project_empty.png
+++ b/doc/user/project/merge_requests/img/approvals_starter_project_empty.png
--- a/doc/user/project/merge_requests/img/approve.png
+++ b/doc/user/project/merge_requests/img/approve.png
--- a/doc/user/project/merge_requests/img/approve_additionally.png
+++ b/doc/user/project/merge_requests/img/approve_additionally.png
--- a/doc/user/project/merge_requests/img/browser_performance_testing.png
+++ b/doc/user/project/merge_requests/img/browser_performance_testing.png
--- a/doc/user/project/merge_requests/img/code_quality.gif
+++ b/doc/user/project/merge_requests/img/code_quality.gif
--- a/doc/user/project/merge_requests/img/container_scanning.png
+++ b/doc/user/project/merge_requests/img/container_scanning.png
--- a/doc/user/project/merge_requests/img/create-issue-with-list-hover.png
+++ b/doc/user/project/merge_requests/img/create-issue-with-list-hover.png
--- a/doc/user/project/merge_requests/img/dast_all.png
+++ b/doc/user/project/merge_requests/img/dast_all.png
--- a/doc/user/project/merge_requests/img/dast_single.png
+++ b/doc/user/project/merge_requests/img/dast_single.png
--- a/doc/user/project/merge_requests/img/dependency_scanning.png
+++ b/doc/user/project/merge_requests/img/dependency_scanning.png
--- a/doc/user/project/merge_requests/img/filter_approver_merge_requests.png
+++ b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png
--- a/doc/user/project/merge_requests/img/interactive_reports.png
+++ b/doc/user/project/merge_requests/img/interactive_reports.png
--- a/doc/user/project/merge_requests/img/license_management.png
+++ b/doc/user/project/merge_requests/img/license_management.png
--- a/doc/user/project/merge_requests/img/license_management_decision.png
+++ b/doc/user/project/merge_requests/img/license_management_decision.png
--- a/doc/user/project/merge_requests/img/license_management_pipeline_tab.png
+++ b/doc/user/project/merge_requests/img/license_management_pipeline_tab.png
--- a/doc/user/project/merge_requests/img/license_management_settings.png
+++ b/doc/user/project/merge_requests/img/license_management_settings.png
--- a/doc/user/project/merge_requests/img/remove_approval.png
+++ b/doc/user/project/merge_requests/img/remove_approval.png
--- a/doc/user/project/merge_requests/img/sast.png
+++ b/doc/user/project/merge_requests/img/sast.png
--- a/doc/user/project/merge_requests/img/security_report.png
+++ b/doc/user/project/merge_requests/img/security_report.png
--- a/doc/user/project/merge_requests/img/vulnerability_solution.png
+++ b/doc/user/project/merge_requests/img/vulnerability_solution.png
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -23,7 +23,7 @@ With GitLab merge requests, you can:
 - Assign it to any registered user, and change the assignee how many times you need
 - Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation
 - Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md)
- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.html#time-tracking)
+- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.md#time-tracking)
 - [Resolve merge conflicts from the UI](#resolve-conflicts)
 - Enable [fast-forward merge requests](#fast-forward-merge-requests)
 - Enable [semi-linear history merge requests](#semi-linear-history-merge-requests) as another security layer to guarantee the pipeline is passing in the target branch
@@ -33,9 +33,16 @@ With GitLab merge requests, you can:
 With **[GitLab Enterprise Edition][ee]**, you can also:
- View the deployment process across projects with [Multi-Project Pipeline Graphs](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html#multi-project-pipeline-graphs) **[PREMIUM]**
+- Prepare a full review and submit it once it's ready with [Merge Request Reviews](https://docs.gitlab.com/ee/user/discussions/index.md#merge-request-reviews-premium) **[PREMIUM]**
- Request [approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers **[STARTER]**
+- View the deployment process across projects with [Multi-Project Pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipelines.md) **[PREMIUM]**
- Analyze the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html) **[STARTER]**
+- Request [approvals](merge_request_approvals.md) from your managers **[STARTER]**
+- Analyze the impact of your changes with [Code Quality reports](code_quality.md) **[STARTER]**
+- Manage the licenses of your dependencies with [License Management](https://docs.gitlab.com/ee/user/application_security/license_management/index.md) **[ULTIMATE]**
+- Analyze your source code for vulnerabilities with [Static Application Security Testing](https://docs.gitlab.com/ee/user/application_security/sast/index.md) **[ULTIMATE]**
+- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](https://docs.gitlab.com/ee/user/application_security/dast/index.md) **[ULTIMATE]**
+- Analyze your dependencies for vulnerabilities with [Dependency Scanning](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.md) **[ULTIMATE]**
+- Analyze your Docker images for vulnerabilities with [Container Scanning](https://docs.gitlab.com/ee/user/application_security/container_scanning/index.md) **[ULTIMATE]**
+- Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **[PREMIUM]**
 ## Use cases
@@ -43,19 +50,21 @@ A. Consider you are a software developer working in a team:
 1. You checkout a new branch, and submit your changes through a merge request
 1. You gather feedback from your team
+1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) **[STARTER]**
 1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD
-1. You request the approval from your manager
+1. You avoid using dependencies whose license is not compatible with your project with [License Management reports](license_management.md) **[ULTIMATE]**
-1. Your manager pushes a commit with his final review, [approves the merge request](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter)
+1. You request the [approval](#merge-request-approvals-starter) from your manager
+1. Your manager pushes a commit with their final review, [approves the merge request](merge_request_approvals.md), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter)
 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD
 1. Your implementations were successfully shipped to your customer
-B. Consider you're a web developer writing a webpage for your company's:
+B. Consider you're a web developer writing a webpage for your company's website:
 1. You checkout a new branch, and submit a new page through a merge request
 1. You gather feedback from your reviewers
 1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md)
 1. You request your web designers for their implementation
-1. You request the [approval](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your manager **[STARTER]**
+1. You request the [approval](merge_request_approvals.md) from your manager **[STARTER]**
 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
 1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production
@@ -159,6 +168,21 @@ in a Merge Request. To do so, click the **...** button in the gutter of the Merg
 ![Comment on any diff file line](img/comment-on-any-diff-line.png)
+## Perform a Review **[PREMIUM]**
+Start a review in order to create multiple comments on a diff and publish them once you're ready.
+Starting a review allows you to get all your thoughts in order and ensure you haven't missed anything
+before submitting all your comments.
+[Learn more about Merge Request Reviews](https://docs.gitlab.com/ee/user/discussions/index.html#merge-request-reviews-premium)
+## Squash and merge
+GitLab allows you to squash all changes present in a merge request into a single
+commit when merging, to allow for a neater commit history.
+[Learn more about squash and merge.](squash_and_merge.md)
 ## Suggest changes
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6.
@@ -182,7 +206,7 @@ To assign multiple assignees to a merge request:
 1. From a merge request, expand the right sidebar and locate the **Assignees** section.
 1. Click on **Edit** and from the dropdown menu, select as many users as you want
-to assign the merge request to.
+   to assign the merge request to.
 Similarly, assignees are removed by deselecting them from the same dropdown menu.
@@ -336,6 +360,52 @@ have been marked as a **Work In Progress**.
 [Learn more about setting a merge request as "Work In Progress".](work_in_progress_merge_requests.md)
+## Merge request approvals **[STARTER]**
+> Included in [GitLab Starter][products].
+If you want to make sure every merge request is approved by one or more people,
+you can enforce this workflow by using merge request approvals. Merge request
+approvals allow you to set the number of necessary approvals and predefine a
+list of approvers that will need to approve every merge request in a project.
+[Read more about merge request approvals.](merge_request_approvals.md)
+## Code Quality **[STARTER]**
+> Introduced in [GitLab Starter][products] 9.3.
+If you are using [GitLab CI][ci], you can analyze your source code quality using
+the [Code Climate][cc] analyzer [Docker image][cd]. Going a step further, GitLab
+can show the Code Climate report right in the merge request widget area.
+[Read more about Code Quality reports.](code_quality.md)
+## Browser Performance Testing **[PREMIUM]**
+> Introduced in [GitLab Premium][products] 10.3.
+If your application offers a web interface and you are using [GitLab CI/CD][ci], you can quickly determine the performance impact of pending code changes. GitLab uses [Sitespeed.io][sitespeed], a free and open source tool for measuring the performance of web sites, to analyze the performance of specific pages.
+GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the difference in overall performance scores between the source and target branches.
+[Read more about Browser Performance Testing.](browser_performance_testing.md)
+## Security reports **[ULTIMATE]**
+GitLab can scan and report any vulnerabilities found in your project.
+[Read more about security reports.](https://docs.gitlab.com/ee/user/application_security/index.html)
+## Live preview with Review Apps
+If you configured [Review Apps](https://about.gitlab.com/features/review-apps/) for your project,
+you can preview the changes submitted to a feature-branch through a merge request
+in a per-branch basis. No need to checkout the branch, install and preview locally;
+all your changes will be available to preview by anyone with the Review Apps link.
+[Read more about Review Apps.](../../../ci/review_apps/index.md)
 ## Merge request diff file navigation
 When reviewing changes in the **Changes** tab the diff can be navigated using
@@ -528,5 +598,11 @@ And to check out a particular merge request:
 git checkout origin/merge-requests/1
 ```
+[products]: https://about.gitlab.com/products/ "GitLab products page"
 [protected branches]: ../protected_branches.md
+[ci]: ../../../ci/README.md
+[cc]: https://codeclimate.com/
+[cd]: https://hub.docker.com/r/codeclimate/codeclimate/
+[sitespeed]: https://www.sitespeed.io
+[sitespeed-container]: https://hub.docker.com/r/sitespeedio/sitespeed.io/
 [ee]: https://about.gitlab.com/pricing/ "GitLab Enterprise Edition"
--- a/doc/user/project/merge_requests/license_management.md
+++ b/doc/user/project/merge_requests/license_management.md
+---
+redirect_to: 'https://docs.gitlab.com/ee/user/application_security/license_management/index.html'
+---
+This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/license_management/index.html).
--- a/doc/user/project/merge_requests/merge_request_approvals.md
+++ b/doc/user/project/merge_requests/merge_request_approvals.md
--- a/doc/user/project/merge_requests/sast.md
+++ b/doc/user/project/merge_requests/sast.md
+---
+redirect_to: 'https://docs.gitlab.com/ee/user/application_security/sast/index.html'
+---
+This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/sast/index.html).
--- a/doc/user/project/merge_requests/sast_docker.md
+++ b/doc/user/project/merge_requests/sast_docker.md
+---
+redirect_to: 'https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html'
+---
+This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html).