Review and revise Custom issue tracker integration UI text

app/models/project_services/custom_issue_tracker_service.rb

 # frozen_string_literal: true
 
 class CustomIssueTrackerService < IssueTrackerService
+  include ActionView::Helpers::UrlHelper
   validates :project_url, :issues_url, :new_issue_url, presence: true, public_url: true, if: :activated?
 
   def title
-    'Custom Issue Tracker'
+    s_('IssueTracker|Custom issue tracker')
   end
 
   def description
-    s_('IssueTracker|Custom issue tracker')
+    s_('IssueTracker|Use a custom issue tracker.')
   end
 
-  def self.to_param
-    'custom_issue_tracker'
+  def help
+    docs_link = link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/project/integrations/custom_issue_tracker'), target: '_blank', rel: 'noopener noreferrer'
+    s_('IssueTracker|Use a custom issue tracker that is not in the integration list. %{docs_link}').html_safe % { docs_link: docs_link.html_safe }
   end
 
-  def fields
-    [
-      { type: 'text', name: 'project_url', title: _('Project URL'), required: true },
-      { type: 'text', name: 'issues_url', title: s_('ProjectService|Issue URL'), required: true },
-      { type: 'text', name: 'new_issue_url', title: s_('ProjectService|New issue URL'), required: true }
-    ]
+  def self.to_param
+    'custom_issue_tracker'
   end
 end

changelogs/unreleased/msj-custom-issue-tracker-okr.yml

+---
+title: Review and revise custom issue tracker UI text
+merge_request: 59277
+author:
+type: other

doc/user/project/integrations/custom_issue_tracker.md

@@ -4,35 +4,43 @@ 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
 ---
 
-# Custom Issue Tracker service **(FREE)**
+# Custom issue tracker service **(FREE)**
 
-To enable the Custom Issue Tracker integration in a project:
+Use a custom issue tracker that is not in the integration list.
 
-1. Go to **Settings > Integrations**.
-1. Click **Custom Issue Tracker**
-1. Fill in the tracker's details, such as title, description, and URLs.
-   You can edit these fields later as well.
+To enable a custom issue tracker in a project:
 
-   These are some of the required fields:
+1. Go to the [Integrations page](overview.md#accessing-integrations).
+1. Select **Custom issue tracker**.
+1. Select the checkbox under **Enable integration**.
+1. Fill in the required fields:
 
-   | Field           | Description |
-   | --------------- | ----------- |
-   | **Project URL**   | The URL to the project in the custom issue tracker. |
-   | **Issues URL**    | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. |
-   | **New issue URL** | Currently unused. Planned to be changed in a future release. |
+   - **Project URL**: The URL to view all the issues in the custom issue tracker.
+   - **Issue URL**: The URL to view an issue in the custom issue tracker. The URL must contain `:id`.
+   GitLab replaces `:id` with the issue number (for example,
+   `https://customissuetracker.com/project-name/:id`, which becomes `https://customissuetracker.com/project-name/123`).
+   - **New issue URL**:
+     <!-- The line below was originally added in January 2018: https://gitlab.com/gitlab-org/gitlab/-/commit/778b231f3a5dd42ebe195d4719a26bf675093350 -->
+     **This URL is not used and removal is planned in a future release.**
+     Enter any URL here.
+     For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503).
 
-1. Click **Test settings and save changes**.
+1. Select **Save changes** or optionally select **Test settings**.
 
-After you configure and enable the Custom Issue Tracker service, you see a link on the GitLab
-project pages that takes you to that custom issue tracker.
+After you configure and enable the custom issue tracker service, a link appears on the GitLab
+project pages. This link takes you to the custom issue tracker.
 
-## Referencing issues
+## Reference issues in a custom issue tracker
 
-Issues are referenced with `<ANYTHING>-<ID>` (for example, `PROJECT-143`), where `<ANYTHING>` can be any string in CAPS, and `<ID>`
-is a number used in the target project of the custom integration.
+You can reference issues in a custom issue tracker using:
 
-`<ANYTHING>` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example.
+- `#<ID>`, where `<ID>` is a number (for example, `#143`).
+- `<PROJECT>-<ID>` (for example `API_32-143`) where:
+  - `<PROJECT>` starts with a capital letter, followed by capital letters, numbers, or underscores.
+  - `<ID>` is a number.
 
-When building the hyperlink, the `<ANYTHING>` part is ignored, and links always point to the address
-specified in `issues_url`, so in the example above, `PROJECT-143` would refer to
-`https://customissuetracker.com/project-name/143`.
+The `<PROJECT>` part is ignored in links, which always point to the address specified in **Issue URL**.
+
+We suggest using the longer format (`<PROJECT>-<ID>`) if you have both internal and external issue
+trackers enabled. If you use the shorter format, and an issue with the same ID exists in the
+internal issue tracker, the internal issue is linked.

locale/gitlab.pot

@@ -17854,6 +17854,12 @@ msgstr ""
 msgid "IssueTracker|Use Redmine as the issue tracker. %{docs_link}"
 msgstr ""
 
+msgid "IssueTracker|Use a custom issue tracker that is not in the integration list. %{docs_link}"
+msgstr ""
+
+msgid "IssueTracker|Use a custom issue tracker."
+msgstr ""
+
 msgid "IssueTracker|YouTrack issue tracker"
 msgstr ""
 

spec/features/projects/services/user_activates_issue_tracker_spec.rb

@@ -87,6 +87,6 @@ RSpec.describe 'User activates issue tracker', :js do
   it_behaves_like 'external issue tracker activation', tracker: 'Redmine'
   it_behaves_like 'external issue tracker activation', tracker: 'YouTrack', skip_new_issue_url: true
   it_behaves_like 'external issue tracker activation', tracker: 'Bugzilla'
-  it_behaves_like 'external issue tracker activation', tracker: 'Custom Issue Tracker'
+  it_behaves_like 'external issue tracker activation', tracker: 'Custom issue tracker'
   it_behaves_like 'external issue tracker activation', tracker: 'EWM', skip_test: true
 end