Merge branch '263371-transition-id-section-should-include-help-text' into 'master'

Add help text to Jira transition ID form field

See merge request gitlab-org/gitlab!49204

app/models/project_services/jira_service.rb

@@ -122,12 +122,15 @@ class JiraService < IssueTrackerService
   end
 
   def fields
+    transition_id_help_path = help_page_path('user/project/integrations/jira', anchor: 'obtaining-a-transition-id')
+    transition_id_help_link_start = '<a href="%{transition_id_help_path}" target="_blank" rel="noopener noreferrer">'.html_safe % { transition_id_help_path: transition_id_help_path }
+
     [
       { type: 'text', name: 'url', title: s_('JiraService|Web URL'), placeholder: 'https://jira.example.com', required: true },
       { type: 'text', name: 'api_url', title: s_('JiraService|Jira API URL'), placeholder: s_('JiraService|If different from Web URL') },
       { type: 'text', name: 'username', title: s_('JiraService|Username or Email'), placeholder: s_('JiraService|Use a username for server version and an email for cloud version'), required: true },
       { type: 'password', name: 'password', title: s_('JiraService|Password or API token'), placeholder: s_('JiraService|Use a password for server version and an API token for cloud version'), required: true },
-      { type: 'text', name: 'jira_issue_transition_id', title: s_('JiraService|Transition ID(s)'), placeholder: s_('JiraService|Use , or ; to separate multiple transition IDs') }
+      { type: 'text', name: 'jira_issue_transition_id', title: s_('JiraService|Jira workflow transition IDs'), placeholder: s_('JiraService|For example, 12, 24'), help: s_('JiraService|Set transition IDs for Jira workflow transitions. %{link_start}Learn more%{link_end}'.html_safe % { link_start: transition_id_help_link_start, link_end: '</a>'.html_safe }) }
     ]
   end
 

changelogs/unreleased/263371-transition-id-section-should-include-help-text.yml

+---
+title: Resolve Transition ID section should include help text
+merge_request: 49204
+author:
+type: added

doc/user/project/integrations/jira.md

@@ -83,7 +83,7 @@ Enter the further details on the page as described in the following table.
 | `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. |
 | `Username or Email` | Created in [configuring Jira](#configuring-jira) step. Use `username` for **Jira Server** or `email` for **Jira Cloud**. |
 | `Password/API token` |Created in [configuring Jira](#configuring-jira) step. Use `password` for **Jira Server** or `API token` for **Jira Cloud**. |
-| `Transition ID` | Required for closing Jira issues via commits or merge requests. This is the ID of a transition in Jira that moves issues to a desired state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. |
+| `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. |
 
 To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)**
 

locale/gitlab.pot

@@ -15684,6 +15684,9 @@ msgstr ""
 msgid "JiraService|Events for %{noteable_model_name} are disabled."
 msgstr ""
 
+msgid "JiraService|For example, 12, 24"
+msgstr ""
+
 msgid "JiraService|If different from Web URL"
 msgstr ""
 
@@ -15708,19 +15711,19 @@ msgstr ""
 msgid "JiraService|Jira project key"
 msgstr ""
 
-msgid "JiraService|Open Jira"
+msgid "JiraService|Jira workflow transition IDs"
 msgstr ""
 
-msgid "JiraService|Password or API token"
+msgid "JiraService|Open Jira"
 msgstr ""
 
-msgid "JiraService|This feature requires a Premium plan."
+msgid "JiraService|Password or API token"
 msgstr ""
 
-msgid "JiraService|Transition ID(s)"
+msgid "JiraService|Set transition IDs for Jira workflow transitions. %{link_start}Learn more%{link_end}"
 msgstr ""
 
-msgid "JiraService|Use , or ; to separate multiple transition IDs"
+msgid "JiraService|This feature requires a Premium plan."
 msgstr ""
 
 msgid "JiraService|Use a password for server version and an API token for cloud version"

spec/models/project_services/jira_service_spec.rb

@@ -66,6 +66,19 @@ RSpec.describe JiraService do
     end
   end
 
+  describe '#fields' do
+    let(:service) { create(:jira_service) }
+
+    subject(:fields) { service.fields }
+
+    it 'includes transition help link' do
+      transition_id_field = fields.find { |field| field[:name] == 'jira_issue_transition_id' }
+
+      expect(transition_id_field[:title]).to eq('Jira workflow transition IDs')
+      expect(transition_id_field[:help]).to include('/help/user/project/integrations/jira')
+    end
+  end
+
   describe 'Associations' do
     it { is_expected.to belong_to :project }
     it { is_expected.to have_one :service_hook }