Add latest changes from gitlab-org/gitlab@master

5 files changed, 45 insertions, 43 deletions

diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md
index a080d513afa..fcee3f7a637 100644
--- a/doc/integration/jira/connect-app.md
+++ b/doc/integration/jira/connect-app.md
@@ -4,21 +4,24 @@ group: Ecosystem
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# GitLab.com for Jira Cloud app **(FREE SAAS)**
+# GitLab.com for Jira Cloud app **(FREE)**
+
+## GitLab.com for Jira Cloud app **(FREE SAAS)**
 
 You can integrate GitLab.com and Jira Cloud using the
 [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud)
-app in the Atlassian Marketplace. The user configuring GitLab.com for Jira Cloud must have
+app in the Atlassian Marketplace. The user configuring GitLab.com for Jira Cloud app must have
 [Maintainer](../../user/permissions.md) permissions in the GitLab.com namespace.
 
 This integration method supports [smart commits](dvcs.md#smart-commits).
 
 This method is recommended when using GitLab.com and Jira Cloud because data is
 synchronized in real-time. The DVCS connector updates data only once per hour.
-If you are not using both of these environments, use the [Jira DVCS Connector](dvcs.md) method.
+If you are not using both of these environments, use the [Jira DVCS Connector](dvcs.md) method or
+[steps to install GitLab.com for Jira Cloud app for self-managed instances](#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances).
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
-For a walkthrough of the integration with GitLab.com for Jira Cloud, watch
+For a walkthrough of the integration with GitLab.com for Jira Cloud app, watch
 [Configure GitLab.com Jira Could Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube.
 
 1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab.
@@ -52,10 +55,10 @@ After a namespace is added:
 
 Support for syncing past branch and commit data [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/263240).
 
-## Install the GitLab.com for Jira Cloud application for self-managed instances **(FREE SELF)**
+## Install the GitLab.com for Jira Cloud app for self-managed instances **(FREE SELF)**
 
 If your GitLab instance is self-managed, you must follow some
-extra steps to install the GitLab.com for Jira Cloud application.
+extra steps to install the GitLab.com for Jira Cloud app.
 
 Each Jira Cloud application must be installed from a single location. Jira fetches
 a [manifest file](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/)
@@ -121,9 +124,9 @@ for details.
 NOTE:
 DVCS means distributed version control system.
 
-## Troubleshooting GitLab.com for Jira Cloud
+## Troubleshooting GitLab.com for Jira Cloud app
 
-The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies. This can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in.
+The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies, which can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in.
 
 > "You need to sign in or sign up before continuing."
 
diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md
index 3aba2e3b3a0..9057267d55e 100644
--- a/doc/integration/jira/development_panel.md
+++ b/doc/integration/jira/development_panel.md
@@ -31,11 +31,6 @@ This integration connects all GitLab projects to projects in the Jira instance i
   including the projects in its subgroups.
 - A personal namespace: Connects the projects in that personal namespace to Jira.
 
-This differs from the [Jira integration](index.md),
-where the mapping is between one GitLab project and the entire Jira instance.
-You can install both integrations to take advantage of both sets of features.
-A [feature comparison](index.md#direct-feature-comparison) is available.
-
 ## Use the integration
 
 After the integration is [set up on GitLab and Jira](#configure-the-integration), you can:
@@ -44,7 +39,8 @@ After the integration is [set up on GitLab and Jira](#configure-the-integration)
   commit messages, and merge request titles.
 - See the linked branches, commits, and merge requests in Jira issues:
 
-Merge requests are called "pull requests" in Jira issues.
+At this time, merge requests are called "pull requests" in Jira issues.
+This name may change in a future Jira release.
 
 Select the links to see your GitLab repository data.
 
@@ -72,13 +68,13 @@ To simplify administration, we recommend that a GitLab group maintainer or group
 
 | Jira usage | GitLab.com customers need | GitLab self-managed customers need |
 |------------|---------------------------|------------------------------------|
-| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-application-for-self-managed-instances) for more information. |
+| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances) for more information. |
 | Your own server | The Jira DVCS (distributed version control system) connector. This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). |
 
 Each GitLab project can be configured to connect to an entire Jira instance. That means after
 configuration, one GitLab project can interact with all Jira projects in that instance. For:
 
-- The [view Jira issues](issues.md#view-jira-issues) feature, you must associate a GitLab project with a
+- The [view Jira issues](issues.md#view-jira-issues) feature **(PREMIUM)**, you must associate a GitLab project with a
   specific Jira project.
 - Other features, you do not have to explicitly associate a GitLab project with any single Jira
   project.
@@ -86,16 +82,16 @@ configuration, one GitLab project can interact with all Jira projects in that in
 If you have a single Jira instance, you can pre-fill the settings. For more information, read the
 documentation for [central administration of project integrations](../../user/admin_area/settings/project_integration_management.md).
 
-To enable the Jira service in GitLab, you must:
+To enable the integration in GitLab, you must:
 
-1. [Configure the project in Jira](dvcs.md#configure-jira-for-dvcs).
+1. [Configure the project in Jira](index.md#jira-integration).
    The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`.
 1. [Enter the correct values in GitLab](#configure-gitlab).
 
 ### Configure GitLab
 
 To enable the integration in your GitLab project, after you
-[configure your Jira project](dvcs.md#configure-jira-for-dvcs):
+[configure your Jira project](index.md#jira-integration):
 
 1. Ensure your GitLab installation does not use a relative URL, as described in
    [Limitations](#limitations).
@@ -114,12 +110,14 @@ To enable the integration in your GitLab project, after you
      this GitLab project, such as `https://jira.example.com`.
    - **Jira API URL**: The base URL to the Jira instance API, such as `https://jira-api.example.com`.
      Defaults to the **Web URL** value if not set. Leave blank if using **Jira on Atlassian cloud**.
-   - **Username or Email**: Created when you [configured Jira](dvcs.md#configure-jira-for-dvcs).
+   - **Username or Email**:
      For **Jira Server**, use `username`. For **Jira on Atlassian cloud**, use `email`.
-   - **Password/API token**: Created when you [configured Jira](dvcs.md#configure-jira-for-dvcs).
+     See [authentication in Jira](index.md#authentication-in-jira).
+   - **Password/API token**:
      Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**.
-1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and
-   enter a Jira project key. **(PREMIUM)**
+     See [authentication in Jira](index.md#authentication-in-jira).
+1. To enable users to view Jira issues inside the GitLab project **(PREMIUM)**, select **Enable Jira issues** and
+   enter a Jira project key.
 
    You can display issues only from a single Jira project in a given GitLab project.
 
@@ -127,7 +125,7 @@ To enable the integration in your GitLab project, after you
    If you enable Jira issues with this setting, all users with access to this GitLab project
    can view all issues from the specified Jira project.
 
-1. To enable issue creation for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**.
+1. To enable issue creation for vulnerabilities **(ULTIMATE)**, select **Enable Jira issues creation from vulnerabilities**.
 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again.
 1. To verify the Jira connection is working, select **Test settings**.
 1. Select **Save changes**.
diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md
index 046dd125cd1..d69243e50a6 100644
--- a/doc/integration/jira/dvcs.md
+++ b/doc/integration/jira/dvcs.md
@@ -7,9 +7,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Jira DVCS connector **(FREE)**
 
 Use the Jira DVCS (distributed version control system) connector if you self-host
-either your Jira instance or your GitLab instance, and you want to sync information
-between them. If you use Jira Cloud and GitLab.com, you should use the
-[GitLab for Jira app](connect-app.md) unless you specifically need the DVCS connector.
+your Jira instance, and you want to sync information
+between GitLab and Jira. If you use Jira Cloud and GitLab.com, you should use the
+[GitLab.com for Jira Cloud app](connect-app.md) unless you specifically need the DVCS connector.
 
 When you configure the Jira DVCS connector, make sure your GitLab and Jira instances
 are accessible.
@@ -67,8 +67,9 @@ your integration.
 
 1. In GitLab, [create a user](../../user/profile/account/create_accounts.md) for Jira to
    use to connect to GitLab. For Jira to access all projects,
-   a user with [Administrator](../../user/permissions.md) permissions must
-   create the user.
+   a user with [administrator](../../user/permissions.md) permissions must
+   create the user with administrator permissions.
+1. Sign in as the `jira` user.
 1. In the top right corner, click the account's avatar, and select **Edit profile**.
 1. In the left sidebar, select **Applications**.
 1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`.
@@ -90,9 +91,6 @@ your integration.
 
 ## Configure Jira for DVCS
 
-If you use Jira Cloud, use the [GitLab for Jira app](connect-app.md)
-unless you specifically need the DVCS Connector.
-
 Configure this connection when you want to import all GitLab commits and branches,
 for the groups you specify, into Jira. This import takes a few minutes and, after
 it completes, refreshes every 60 minutes:
diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md
index 2646a6c5e2e..4219cb915cc 100644
--- a/doc/integration/jira/index.md
+++ b/doc/integration/jira/index.md
@@ -7,12 +7,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Jira integrations **(FREE)**
 
 If your organization uses [Jira](https://www.atlassian.com/software/jira) issues,
-you can [migrate](../../user/project/import/jira.md) your issues from Jira and work
+you can [migrate your issues from Jira](../../user/project/import/jira.md) **(PREMIUM)** and work
 exclusively in GitLab. However, if you'd like to continue to use Jira, you can
 integrate it with GitLab. GitLab offers two types of Jira integrations, and you
-can use one or both depending on the capabilities you need.
+can use one or both depending on the capabilities you need. It is recommended that you enable both.
 
-## Compare Jira integrations
+## Compare integrations
 
 After you set up one or both of these integrations, you can cross-reference activity
 in your GitLab project with any of your projects in Jira.
@@ -20,10 +20,13 @@ in your GitLab project with any of your projects in Jira.
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be).
 
-### Per-project Jira integration
+### Jira integration
 
-This integration connects a single GitLab project to a Jira instance. The Jira instance
-can be hosted by you or in [Atlassian cloud](https://www.atlassian.com/cloud):
+This integration connects one or more GitLab project to a Jira instance. The Jira instance
+can be hosted by you or in [Atlassian cloud](https://www.atlassian.com/cloud).
+The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`.
+To simplify administration, we recommend that a GitLab group maintainer or group owner
+(or instance administrator in the case of self-managed GitLab) set up the integration.
 
 - *If your installation uses Jira Cloud,* use the
   [GitLab for Jira app](connect-app.md).
@@ -48,7 +51,7 @@ displays in the [development panel](https://support.atlassian.com/jira-software-
 | Add Jira time tracking to an issue. | No. | Yes. Time can be specified using Jira Smart Commits. |
 | Use a Git commit or merge request to transition or close a Jira issue. | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. |
 | Display a list of Jira issues. | Yes. **(PREMIUM)** | No. |
-| Create a Jira issue from a vulnerability or finding. **(ULTIMATE)** | Yes. | No. |
+| Create a Jira issue from a vulnerability or finding. | Yes. **(ULTIMATE)** | No. |
 
 ## Authentication in Jira
 
@@ -64,10 +67,10 @@ The process for configuring Jira depends on whether you host Jira on your own se
 
 ## Privacy considerations
 
-If you integrate a private GitLab project with Jira using the [**Per-project Jira integration**](#per-project-jira-integration),
+If you integrate a private GitLab project with Jira using the [**Jira integration**](#jira-integration),
 actions in GitLab issues and merge requests linked to a Jira issue leak information
 about the private project to non-administrator Jira users. If your installation uses Jira Cloud,
-you can use the [GitLab for Jira app](connect-app.md) to avoid this risk.
+you can use the [GitLab.com for Jira Cloud app](connect-app.md) to avoid this risk.
 
 ## Troubleshooting
 
diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md
index aafc9956b4e..34ca5481b85 100644
--- a/doc/integration/jira/issues.md
+++ b/doc/integration/jira/issues.md
@@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Jira integration issue management **(FREE)**
 
-Integrating issue management with Jira requires you to [configure Jira](development_panel.md#configure-the-integration)
+Integrating issue management with Jira requires you to [configure Jira](index.md#jira-integration)
 and [enable the Jira service](development_panel.md#configure-gitlab) in GitLab.
 After you configure and enable the integration, you can reference and close Jira
 issues by mentioning the Jira ID in GitLab commits and merge requests.
@@ -122,7 +122,7 @@ Issues are grouped into tabs based on their
 - **Closed** tab: All issues with a Jira status categorized as Done.
 - **All** tab: All issues of any status.
 
-## Search and filter the issues list
+### Search and filter the issues list **(PREMIUM)**
 
 To refine the list of issues, use the search bar to search for any text
 contained in an issue summary (title) or description. Use any combination