Revise Pivotal Tracker project integration: style, docs

app/models/integrations/pivotaltracker.rb

@@ -2,17 +2,23 @@
 
 module Integrations
   class Pivotaltracker < Integration
+    include ActionView::Helpers::UrlHelper
     API_ENDPOINT = 'https://www.pivotaltracker.com/services/v5/source_commits'
 
     prop_accessor :token, :restrict_to_branch
     validates :token, presence: true, if: :activated?
 
     def title
-      'PivotalTracker'
+      'Pivotal Tracker'
     end
 
     def description
-      s_('PivotalTrackerService|Add commit messages as comments to PivotalTracker stories.')
+      s_('PivotalTrackerService|Add commit messages as comments to Pivotal Tracker stories.')
+    end
+
+    def help
+      docs_link = link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/project/integrations/pivotal_tracker'), target: '_blank', rel: 'noopener noreferrer'
+      s_('Add commit messages as comments to Pivotal Tracker stories. %{docs_link}').html_safe % { docs_link: docs_link.html_safe }
     end
 
     def self.to_param
@@ -24,14 +30,15 @@ module Integrations
         {
           type: 'text',
           name: 'token',
-          placeholder: s_('PivotalTrackerService|Pivotal Tracker API token.'),
+          help: s_('PivotalTrackerService|Pivotal Tracker API token. User must have access to the story. All comments are attributed to this user.'),
           required: true
         },
         {
           type: 'text',
           name: 'restrict_to_branch',
-          placeholder: s_('PivotalTrackerService|Comma-separated list of branches which will be ' \
-            'automatically inspected. Leave blank to include all branches.')
+          title: 'Restrict to branch (optional)',
+          help: s_('PivotalTrackerService|Comma-separated list of branches to ' \
+            'automatically inspect. Leave blank to include all branches.')
         }
       ]
     end

doc/api/services.md

@@ -955,13 +955,15 @@ Get Pipeline-Emails service settings for a project.
 GET /projects/:id/services/pipelines-email
 ```
 
-## PivotalTracker
+## Pivotal Tracker
 
-Project Management Software (Source Commits Endpoint)
+Add commit messages as comments to Pivotal Tracker stories.
+
+See also the [Pivotal Tracker service documentation](../user/project/integrations/pivotal_tracker.md).
 
-### Create/Edit PivotalTracker service
+### Create/Edit Pivotal Tracker service
 
-Set PivotalTracker service for a project.
+Set Pivotal Tracker service for a project.
 
 ```plaintext
 PUT /projects/:id/services/pivotaltracker
@@ -971,21 +973,21 @@ Parameters:
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `token` | string | true | The PivotalTracker token |
+| `token` | string | true | The Pivotal Tracker token |
 | `restrict_to_branch` | boolean | false | Comma-separated list of branches to automatically inspect. Leave blank to include all branches. |
 | `push_events` | boolean | false | Enable notifications for push events |
 
-### Delete PivotalTracker service
+### Delete Pivotal Tracker service
 
-Delete PivotalTracker service for a project.
+Delete Pivotal Tracker service for a project.
 
 ```plaintext
 DELETE /projects/:id/services/pivotaltracker
 ```
 
-### Get PivotalTracker service settings
+### Get Pivotal Tracker service settings
 
-Get PivotalTracker service settings for a project.
+Get Pivotal Tracker service settings for a project.
 
 ```plaintext
 GET /projects/:id/services/pivotaltracker

doc/user/project/integrations/overview.md

@@ -15,11 +15,9 @@ functionality to GitLab.
 You can find the available integrations under your project's
 **Settings > Integrations** page.
 
-There are more than 20 integrations to integrate with. Click on the one that you
+There are more than 20 integrations to integrate with. Select the one that you
 want to configure.
 
-![Integrations list](img/project_integrations_v13_3.png)
-
 ## Integrations listing
 
 Click on the service links to see further configuration instructions and details.
@@ -51,7 +49,7 @@ Click on the service links to see further configuration instructions and details
 | [Microsoft Teams notifications](microsoft_teams.md)       | Receive event notifications.                                                                 | **{dotted-circle}** No |
 | Packagist                                                 | Update your projects.                                                                        | **{check-circle}** Yes |
 | Pipelines emails                                          | Send the pipeline status to a list of recipients by email.                                   | **{dotted-circle}** No |
-| PivotalTracker                                            | Use PivotalTracker as the issue tracker.                                                     | **{dotted-circle}** No |
+| [Pivotal Tracker](pivotal_tracker.md)                      | Add commit messages as comments to Pivotal Tracker stories.                                                    | **{dotted-circle}** No |
 | [Prometheus](prometheus.md)                               | Monitor application metrics.                                                                 | **{dotted-circle}** No |
 | Pushover                                                  | Get real-time notifications on your device.                                                  | **{dotted-circle}** No |
 | [Redmine](redmine.md)                                     | Use Redmine as the issue tracker.                                                            | **{dotted-circle}** No |

doc/user/project/integrations/pivotal_tracker.md

+---
+stage: Create
+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
+---
+
+# Pivotal Tracker service **(FREE)**
+
+This service adds commit messages as comments to Pivotal Tracker stories.
+
+Once enabled, commit messages are checked for square brackets containing a hash mark followed by
+the story ID (for example, `[#555]`). Every story ID found gets the commit comment added to it.
+
+You can also close a story with a message containing: `fix [#555]`.
+You can use any of these words:
+
+- `fix`
+- `fixed`
+- `fixes`
+- `complete`
+- `completes`
+- `completed`
+- `finish`
+- `finished`
+- `finishes`
+- `delivers`
+
+Read more about the
+[Source Commits endpoint](https://www.pivotaltracker.com/help/api/rest/v5#Source_Commits) in
+the Pivotal Tracker API documentation.
+
+See also the [Pivotal Tracker service API documentation](../../../api/services.md#pivotal-tracker).
+
+## Set up Pivotal Tracker
+
+In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/articles/api_token/).
+
+Complete these steps in GitLab:
+
+1. Go to the project you want to configure.
+1. Go to the [Integrations page](overview.md#accessing-integrations).
+1. Select **Pivotal Tracker**.
+1. Ensure that the **Active** toggle is enabled.
+1. Paste the token you generated in Pivotal Tracker.
+1. (Optional) To restrict this setting to specific branches, list them in the **Restrict to branch**
+   field, separated with commas.
+1. Select **Save changes** or optionally select **Test settings**.

locale/gitlab.pot

@@ -1984,6 +1984,9 @@ msgstr ""
 msgid "Add commit messages as comments to Asana tasks. %{docs_link}"
 msgstr ""
 
+msgid "Add commit messages as comments to Pivotal Tracker stories. %{docs_link}"
+msgstr ""
+
 msgid "Add deploy freeze"
 msgstr ""
 
@@ -24476,13 +24479,13 @@ msgstr ""
 msgid "Pipeline|with stages"
 msgstr ""
 
-msgid "PivotalTrackerService|Add commit messages as comments to PivotalTracker stories."
+msgid "PivotalTrackerService|Add commit messages as comments to Pivotal Tracker stories."
 msgstr ""
 
-msgid "PivotalTrackerService|Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches."
+msgid "PivotalTrackerService|Comma-separated list of branches to automatically inspect. Leave blank to include all branches."
 msgstr ""
 
-msgid "PivotalTrackerService|Pivotal Tracker API token."
+msgid "PivotalTrackerService|Pivotal Tracker API token. User must have access to the story. All comments are attributed to this user."
 msgstr ""
 
 msgid "Plain diff"

spec/features/projects/integrations/user_activates_pivotaltracker_spec.rb

@@ -10,11 +10,11 @@ RSpec.describe 'User activates PivotalTracker' do
   end
 
   it 'activates service', :js do
-    visit_project_integration('PivotalTracker')
+    visit_project_integration('Pivotal Tracker')
     fill_in('Token', with: 'verySecret')
 
     click_test_then_save_integration(expect_test_to_fail: false)
 
-    expect(page).to have_content('PivotalTracker settings saved and active.')
+    expect(page).to have_content('Pivotal Tracker settings saved and active.')
   end
 end