Merge branch '323622-aqualls-revise-jira' into 'master'

Revise and clean up Jira issues page

See merge request gitlab-org/gitlab!60751

doc/integration/jira/issues.md

@@ -6,168 +6,157 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Jira integration issue management **(FREE)**
 
-By now you should have [configured Jira](development_panel.md#configuration) and enabled the
-[Jira service in GitLab](development_panel.md#configure-gitlab). If everything is set up correctly
-you should be able to reference and close Jira issues by just mentioning their
-ID in GitLab commits and merge requests.
+Integrating issue management with Jira requires you to [configure Jira](development_panel.md#configuration)
+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.
 
-Jira issue IDs must be formatted in uppercase for the integration to work.
+The Jira integration requires to you format any Jira issue IDs in uppercase.
 
 ## Reference Jira issues
 
-When GitLab project has Jira issue tracker configured and enabled, mentioning
-Jira issues in GitLab automatically adds a comment in Jira issue with the
-link back to GitLab. This means that in comments in merge requests and commits
-referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the
-format:
+With this integration, you can cross-reference Jira issues while you work in
+GitLab issues and merge requests. Mention a Jira issue in a GitLab issue,
+merge request, or comment, and GitLab adds a formatted comment to the Jira issue.
+The comment links back to your work in GitLab.
 
-```plaintext
-USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]:
-ENTITY_TITLE
+For example, this commit references the Jira issue `GIT-1`:
+
+```shell
+git commit -m "GIT-1 this is a test commit"
 ```
 
-- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab.
-- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned.
-- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request.
-- `PROJECT_NAME` GitLab project name.
-- `ENTITY_TITLE` Merge request title or commit message first line.
+GitLab adds a reference to the **Issue Links** section of Jira issue `GIT-1`:
 
-![example of mentioning or closing the Jira issue](img/jira_issue_reference.png)
+![Example of mentioning or closing the Jira issue](img/jira_issue_reference.png)
 
-For example, the following commit references the Jira issue with `PROJECT-1` as its ID:
+GitLab also adds a comment to the issue, and uses this format:
 
-```shell
-git commit -m "PROJECT-1 Fix spelling and grammar"
+```plaintext
+USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]:
+ENTITY_TITLE
 ```
 
-## Close Jira issues
+- `USER`: The name of the user who mentioned the issue, linked to their GitLab user profile.
+- `COMMENTLINK`: A link to where the Jira issue was mentioned.
+- `RESOURCE_NAME`: The type of resource, such as a commit or merge request, which referenced the issue.
+- `PROJECT_NAME`: The GitLab project name.
+- `ENTITY_TITLE`: The title of the merge request, or the first line of the commit.
 
-Jira issues can be closed directly from GitLab by using trigger words in
-commits and merge requests. When a commit which contains the trigger word
-followed by the Jira issue ID in the commit message is pushed, GitLab
-adds a comment in the mentioned Jira issue and immediately closes it (provided
-the transition ID was set up correctly).
+You can [disable comments](#disable-comments-on-jira-issues) on issues.
 
-There are currently three trigger words, and you can use either one to achieve
-the same goal:
+## Close Jira issues in GitLab
 
-- `Resolves PROJECT-1`
-- `Closes PROJECT-1`
-- `Fixes PROJECT-1`
-
-where `PROJECT-1` is the ID of the Jira issue.
+If you have configured GitLab transition IDs, you can close a Jira issue directly
+from GitLab. Use a trigger word followed by a Jira issue ID in a commit or merge request.
+When you push a commit containing a trigger word and Jira issue ID, GitLab:
 
-Note the following:
+1. Comments in the mentioned Jira issue.
+1. Closes the Jira issue. If the Jira issue has a resolution, it isn't transitioned.
 
-- Only commits and merges into the project's default branch (usually `master`)
-  close an issue in Jira. You can change your project's default branch under
-  [project settings](img/jira_project_settings.png).
-- The Jira issue is not transitioned if it has a resolution.
+For example, use any of these trigger words to close the Jira issue `PROJECT-1`:
 
-Let's consider the following example:
-
-1. For the project named `PROJECT` in Jira, we implemented a new feature
-   and created a merge request in GitLab.
-1. This feature was requested in Jira issue `PROJECT-7` and the merge request
-   in GitLab contains the improvement
-1. In the merge request description we use the issue closing trigger
-   `Closes PROJECT-7`.
-1. Once the merge request is merged, the Jira issue is automatically closed
-   with a comment and an associated link to the commit that resolved the issue.
+- `Resolves PROJECT-1`
+- `Closes PROJECT-1`
+- `Fixes PROJECT-1`
 
-In the following screenshot you can see what the link references to the Jira
-issue look like.
+The commit or merge request must target your project's [default branch](../../user/project/repository/branches/default.md).
+You can change your project's default branch under [project settings](img/jira_project_settings.png).
 
-![A Git commit that causes the Jira issue to be closed](img/jira_merge_request_close.png)
+### Use case for closing issues
 
-Once this merge request is merged, the Jira issue is automatically closed
-with a link to the commit that resolved the issue.
+Consider this example:
 
-![The GitLab integration closes Jira issue](img/jira_service_close_issue.png)
+1. A user creates Jira issue `PROJECT-7` to request a new feature.
+1. You create a merge request in GitLab to build the requested feature.
+1. In the merge request, you add the issue closing trigger `Closes PROJECT-7`.
+1. When the merge request is merged:
+   - GitLab closes the Jira issue for you:
+     ![The GitLab integration closes Jira issue](img/jira_service_close_issue.png)
+   - GitLab adds a formatted comment to Jira, linking back to the commit that
+     resolved the issue. You can [disable comments](#disable-comments-on-jira-issues).
 
 ## View Jira issues **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
 
 You can browse, search, and view issues from a selected Jira project directly in GitLab,
-if your GitLab administrator [has configured it](development_panel.md#configure-gitlab):
-
-1. In the left navigation bar, go to **Jira > Issues list**.
-1. The issue list sorts by **Created date** by default, with the newest issues listed at the top:
-
-   ![Jira issues integration enabled](img/open_jira_issues_list_v13.2.png)
+if your GitLab administrator [has configured it](development_panel.md#configure-gitlab).
 
-1. To display the most recently updated issues first, click **Last updated**.
-1. In GitLab versions 13.10 and later, you can view [individual Jira issues](#view-a-jira-issue).
+To do this, in GitLab, go to your project and select **Jira > Issues list**. The issue list
+sorts by **Created date** by default, with the newest issues listed at the top:
 
-Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html):
+![Jira issues integration enabled](img/open_jira_issues_list_v13.2.png)
 
-- The **Open** tab displays all issues with a Jira status in any category other than Done.
-- The **Closed** tab displays all issues with a Jira status categorized as Done.
-- The **All** tab displays all issues of any status.
+- To display the most recently updated issues first, select **Last updated**.
+- You can [search and filter](#search-and-filter-the-issues-list) the issues list.
+- In GitLab [versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/299832),
+  you can select an issue from the list to view it in GitLab:
+  ![Jira issue detail view](img/jira_issue_detail_view_v13.10.png)
 
-## View a Jira issue
+Issues are grouped into tabs based on their
+[Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html):
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10 behind a feature flag, disabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11.
-
-When viewing the [Jira issues list](#view-jira-issues), select an issue from the
-list to open it in GitLab:
-
-![Jira issue detail view](img/jira_issue_detail_view_v13.10.png)
+- **Open** tab: All issues with a Jira status in any category other than Done.
+- **Closed** tab: All issues with a Jira status categorized as Done.
+- **All** tab: All issues of any status.
 
 ## Search and filter the issues list
 
 To refine the list of issues, use the search bar to search for any text
-contained in an issue summary (title) or description.
-
-You can also filter by labels, status, reporter, and assignee using URL parameters.
-Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622).
+contained in an issue summary (title) or description. Use any combination
+of these filters:
 
 - To filter issues by `labels`, specify one or more labels as part of the `labels[]`
-parameter in the URL. When using multiple labels, only issues that contain all specified
-labels are listed. `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA`
-
-- To filter issues by `status`, specify the `status` parameter in the URL.
-`/-/integrations/jira/issues?status=In Progress`
-
+  parameter in the URL. When using multiple labels, only issues that contain all specified
+  labels are listed: `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA`
+- To filter issues by `status`, specify the `status` parameter in the URL:
+  `/-/integrations/jira/issues?status=In Progress`
 - To filter issues by `reporter`, specify a reporter's Jira display name for the
-`author_username` parameter in the URL. `/-/integrations/jira/issues?author_username=John Smith`
-
+  `author_username` parameter in the URL: `/-/integrations/jira/issues?author_username=John Smith`
 - To filter issues by `assignee`, specify their Jira display name for the
-`assignee_username` parameter in the URL. `/-/integrations/jira/issues?assignee_username=John Smith`
+  `assignee_username` parameter in the URL: `/-/integrations/jira/issues?assignee_username=John Smith`
+
+Enhancements to use these filters through the user interface
+[are planned](https://gitlab.com/groups/gitlab-org/-/epics/3622).
 
 ## Automatic issue transitions
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/...) in GitLab 13.10.
 
-In this mode the referenced Jira issue is transitioned to the next available status with a category of "Done".
+When you configure automatic issue transitions, you can transition a referenced
+Jira issue to the next available status with a category of **Done**. To configure
+this setting:
 
-See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting and select the **Move to Done** option.
+1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions.
+1. Select the **Enable Jira transitions** check box.
+1. Select the **Move to Done** option.
 
 ## Custom issue transitions
 
-For advanced workflows you can specify custom Jira transition IDs.
-
-See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting, select the **Custom transitions** option, and enter your transition IDs in the text field.
-
-If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. If a transition fails the sequence is aborted.
-
-To see the transition IDs on Jira Cloud, edit a workflow in the **Text** view.
-The transition IDs display in the **Transitions** column.
-
-On Jira Server you can get the transition IDs in either of the following ways:
-
-1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions`
-   using an issue that is in the appropriate "open" state
-1. By mousing over the link for the transition you want and looking for the
-   "action" parameter in the URL
-
-Note that the transition ID may vary between workflows (for example, bug vs. story),
-even if the status you are changing to is the same.
-
-## Disabling comments on Jira issues
-
-You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue.
-
-See the [Configure GitLab](development_panel.md#configure-gitlab) section and uncheck the **Enable comments** setting.
+For advanced workflows, you can specify custom Jira transition IDs:
+
+1. Use the method based on your Jira subscription status:
+   - *(For users of Jira Cloud)* Obtain your transition IDs by editing a workflow
+     in the **Text** view. The transition IDs display in the **Transitions** column.
+   - *(For users of Jira Server)* Obtain your transition IDs in one of these ways:
+     - By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions`,
+       using an issue that is in the appropriate "open" state.
+     - By mousing over the link for the transition you want and looking for the
+       **action** parameter in the URL.
+   The transition ID may vary between workflows (for example, a bug instead of a
+   story), even if the status you're changing to is the same.
+1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions.
+1. Select the **Enable Jira transitions** setting.
+1. Select the **Custom transitions** option.
+1. Enter your transition IDs in the text field. If you insert multiple transition IDs
+   (separated by `,` or `;`), the issue is moved to each state, one after another, in the
+   order you specify. If a transition fails, the sequence is aborted.
+
+## Disable comments on Jira issues
+
+GitLab can cross-link source commits or merge requests with Jira issues without
+adding a comment to the Jira issue:
+
+1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions.
+1. Clear the **Enable comments** check box.