Review and revise Irker settings UI text

app/models/integrations/irker.rb

@@ -4,6 +4,8 @@
 
 module Integrations
   class Irker < Integration
+    include ActionView::Helpers::UrlHelper
+
     prop_accessor :server_host, :server_port, :default_irc_uri
     prop_accessor :recipients, :channels
     boolean_accessor :colorize_messages
@@ -12,11 +14,11 @@ class Irker < Integration
     before_validation :get_channels
 
     def title
-      'Irker (IRC gateway)'
+      s_('IrkerService|irker (IRC gateway)')
     end
 
     def description
-      'Send IRC messages.'
+      s_('IrkerService|Send update messages to an irker server.')
     end
 
     def self.to_param
@@ -42,33 +44,25 @@ def settings
     end
 
     def fields
+      recipients_docs_link = link_to s_('IrkerService|How to enter channels or users?'), Rails.application.routes.url_helpers.help_page_url('user/project/integrations/irker', anchor: 'enter-irker-recipients'), target: '_blank', rel: 'noopener noreferrer'
       [
-        { type: 'text', name: 'server_host', placeholder: 'localhost',
-          help: 'Irker daemon hostname (defaults to localhost)' },
-        { type: 'text', name: 'server_port', placeholder: 6659,
-          help: 'Irker daemon port (defaults to 6659)' },
-        { type: 'text', name: 'default_irc_uri', title: 'Default IRC URI',
-          help: 'A default IRC URI to prepend before each recipient (optional)',
+        { type: 'text', name: 'server_host', placeholder: 'localhost', title: s_('IrkerService|Server host (optional)'),
+          help: s_('IrkerService|irker daemon hostname (defaults to localhost).') },
+        { type: 'text', name: 'server_port', placeholder: 6659, title: s_('IrkerService|Server port (optional)'),
+          help: s_('IrkerService|irker daemon port (defaults to 6659).') },
+        { type: 'text', name: 'default_irc_uri', title: s_('IrkerService|Default IRC URI (optional)'),
+          help: s_('IrkerService|URI to add before each recipient.'),
           placeholder: 'irc://irc.network.net:6697/' },
-        { type: 'textarea', name: 'recipients',
-          placeholder: 'Recipients/channels separated by whitespaces', required: true,
-          help: 'Recipients have to be specified with a full URI: '\
-          'irc[s]://irc.network.net[:port]/#channel. Special cases: if '\
-          'you want the channel to be a nickname instead, append ",isnick" to ' \
-          'the channel name; if the channel is protected by a secret password, ' \
-          ' append "?key=secretpassword" to the URI (Note that due to a bug, if you ' \
-          ' want to use a password, you have to omit the "#" on the channel). If you ' \
-          ' specify a default IRC URI to prepend before each recipient, you can just ' \
-          ' give a channel name.' },
-        { type: 'checkbox', name: 'colorize_messages' }
+        { type: 'textarea', name: 'recipients', title: s_('IrkerService|Recipients'),
+          placeholder: 'irc[s]://irc.network.net[:port]/#channel', required: true,
+          help: s_('IrkerService|Channels and users separated by whitespaces. %{recipients_docs_link}').html_safe % { recipients_docs_link: recipients_docs_link.html_safe } },
+        { type: 'checkbox', name: 'colorize_messages', title: _('Colorize messages') }
       ]
     end
 
     def help
-      ' NOTE: Irker does NOT have built-in authentication, which makes it' \
-      ' vulnerable to spamming IRC channels if it is hosted outside of a ' \
-      ' firewall. Please make sure you run the daemon within a secured network ' \
-      ' to prevent abuse. For more details, read: http://www.catb.org/~esr/irker/security.html.'
+      docs_link = link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/project/integrations/irker', anchor: 'set-up-an-irker-daemon'), target: '_blank', rel: 'noopener noreferrer'
+      s_('IrkerService|Send update messages to an irker server. Before you can use this, you need to set up the irker daemon. %{docs_link}').html_safe % { docs_link: docs_link.html_safe }
     end
 
     private

doc/.vale/gitlab/spelling-exceptions.txt

@@ -270,7 +270,7 @@ innersourcing
 interdependencies
 interdependency
 interruptible
-Irker
+irker
 issuables
 Istio
 Jaeger

doc/administration/logs.md

@@ -342,7 +342,7 @@ Depending on your installation method, this file is located at:
 - Installations from source: `/home/git/gitlab/log/integrations_json.log`
 
 It contains information about [integration](../user/project/integrations/overview.md)
-activities, such as Jira, Asana, and Irker services. It uses JSON format,
+activities, such as Jira, Asana, and irker services. It uses JSON format,
 like this example:
 
 ```json

doc/api/services.md

@@ -695,16 +695,15 @@ Get Hangouts Chat service settings for a project.
 GET /projects/:id/services/hangouts-chat
 ```
 
-## Irker (IRC gateway)
+## irker (IRC gateway)
 
-Send IRC messages, on update, to a list of recipients through an Irker gateway.
+Send IRC messages, on update, to a list of recipients through an irker gateway.
 
-### Create/Edit Irker (IRC gateway) service
+For more information, see the [irker integration documentation](../user/project/integrations/irker.md).
 
-Set Irker (IRC gateway) service for a project.
+### Create/Edit irker (IRC gateway) service
 
-NOTE:
-Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read [Security analysis of `irker`](http://www.catb.org/~esr/irker/security.html).
+Set irker (IRC gateway) service for a project.
 
 ```plaintext
 PUT /projects/:id/services/irker
@@ -721,17 +720,17 @@ Parameters:
 | `colorize_messages` | boolean | false | Colorize messages |
 | `push_events` | boolean | false | Enable notifications for push events |
 
-### Delete Irker (IRC gateway) service
+### Delete irker (IRC gateway) service
 
-Delete Irker (IRC gateway) service for a project.
+Delete irker (IRC gateway) service for a project.
 
 ```plaintext
 DELETE /projects/:id/services/irker
 ```
 
-### Get Irker (IRC gateway) service settings
+### Get irker (IRC gateway) service settings
 
-Get Irker (IRC gateway) service settings for a project.
+Get irker (IRC gateway) service settings for a project.
 
 ```plaintext
 GET /projects/:id/services/irker

doc/user/project/integrations/irker.md

@@ -4,57 +4,69 @@ 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
 ---
 
-# Irker IRC Gateway **(FREE)**
+# irker IRC Gateway **(FREE)**
 
-GitLab provides a way to push update messages to an Irker server. When
+GitLab provides a way to push update messages to an irker server. When
 configured, pushes to a project trigger the service to send data directly
-to the Irker server.
+to the irker server.
 
-See the [project homepage](https://gitlab.com/esr/irker) for further information.
+See also the [irker integration API documentation](../../../api/services.md).
 
-## Needed setup
+For more information, see the [irker project homepage](https://gitlab.com/esr/irker).
 
-You first need an Irker daemon. You can download the Irker code
-[from its repository](https://gitlab.com/esr/irker):
+## Set up an irker daemon
 
-```shell
-git clone https://gitlab.com/esr/irker.git
-```
+You need to set up an irker daemon. To do so:
 
-Once you have downloaded the code, you can run the Python script named `irkerd`.
-This script is the gateway script, it acts both as an IRC client, for sending
-messages to an IRC server, and as a TCP server, for receiving messages
-from the GitLab service.
+1. Download the irker code [from its repository](https://gitlab.com/esr/irker):
 
-If the Irker server runs on the same machine, you are done. If not, you
+   ```shell
+   git clone https://gitlab.com/esr/irker.git
+   ```
+
+1. Run the Python script named `irkerd`. This is the gateway script.
+   It acts both as an IRC client, for sending messages to an IRC server,
+   and as a TCP server, for receiving messages from the GitLab service.
+
+If the irker server runs on the same machine, you are done. If not, you
 need to follow the first steps of the next section.
 
+WARNING:
+irker does **not** have built-in authentication, which makes it vulnerable to spamming IRC channels if
+it is hosted outside of a firewall. To prevent abuse, make sure you run the daemon on a secured
+network. For more details, read
+[Security analysis of irker](http://www.catb.org/~esr/irker/security.html).
+
 ## Complete these steps in GitLab
 
-1. Navigate to the project you want to configure for notifications.
-1. Navigate to the [Integrations page](overview.md#accessing-integrations)
-1. Click "Irker".
+1. On the top bar, select **Menu > Projects** and find the project you want to
+   configure for notifications.
+1. Navigate to the [Integrations page](overview.md#accessing-integrations).
+1. Select **irker (IRC gateway)**.
 1. Ensure that the **Active** toggle is enabled.
-1. Enter the server host address where `irkerd` runs (defaults to `localhost`)
-   in the `Server host` field on the Web page
-1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the
-   `Server port` field on the Web page.
-1. Optional: if `Default IRC URI` is set, it has to be in the format
-   `irc[s]://domain.name` and is prepended to each and every channel provided
-   by the user which is not a full URI.
-1. Specify the recipients (e.g. #channel1, user1, etc.)
-1. Save or optionally click "Test Settings".
-
-## Note on Irker recipients
-
-Irker accepts channel names of the form `chan` and `#chan`, both for the
-`#chan` channel. If you want to send messages in query, you need to add
-`,isnick` after the channel name, in this form: `Aorimn,isnick`. In this latter
-case, `Aorimn` is treated as a nick and no more as a channel name.
-
-Irker can also join password-protected channels. Users need to append
-`?key=thesecretpassword` to the channel name. When using this feature remember to
-**not** put the `#` sign in front of the channel name; failing to do so
-results in Irker joining a channel literally named `#chan?key=password` henceforth
-leaking the channel key through the `/whois` IRC command (depending on IRC server
-configuration). This is due to a long standing Irker bug.
+1. Optional. Under **Server host**, enter the server host address where `irkerd` runs. If empty,
+   it defaults to `localhost`.
+1. Optional. Under **Server port**, enter the server port of `irkerd`. If empty, it defaults to `6659`.
+1. Optional. Under **Default IRC URI**, enter the default IRC URI, in the format `irc[s]://domain.name`.
+   It's prepended to every channel or user provided under **Recipients**, which is not a full URI.
+1. Under **Recipients**, enter the users or channels to receive updates, separated by spaces
+   (for example, `#channel1 user1`). For more details, see [Enter irker recipients](#enter-irker-recipients).
+1. Optional. Under **Colorize messages**, select the checkbox. irker will highlight your messages.
+1. Select **Save changes** or optionally select **Test Settings**.
+
+## Enter irker recipients
+
+If you left the **Default IRC URI** field empty, enter recipients as a full URI:
+`irc[s]://irc.network.net[:port]/#channel`. If you entered a default IRC URI there, you can use just
+channel or user names.
+
+To send messages:
+
+- To a channel (for example, `#chan`), irker accepts channel names of the form `chan` and
+  `#chan`.
+- To a password-protected channel, append `?key=thesecretpassword` to the channel name,
+  with the channel password instead of `thesecretpassword`. For example, `chan?key=hunter2`.
+  Do **not** put the `#` sign in front of the channel name. If you do, irker tries to join a
+  channel named `#chan?key=password` and so it can leak the channel password through the
+  `/whois` IRC command. This is due to a long-standing irker bug.
+- In a user query, add `,isnick` after the user name. For example, `UserSmith,isnick`.

doc/user/project/integrations/overview.md

@@ -41,7 +41,7 @@ Click on the service links to see further configuration instructions and details
 | [Flowdock](../../../api/services.md#flowdock)             | Send notifications from GitLab to Flowdock flows. | **{dotted-circle}** No |
 | [GitHub](github.md)                                       | Obtain statuses for commits and pull requests.                                               | **{dotted-circle}** No |
 | [Google Chat](hangouts_chat.md)                           | Send notifications from your GitLab project to a room in Google Chat.| **{dotted-circle}** No |
-| [Irker (IRC gateway)](irker.md)                           | Send IRC messages.                                                                           | **{dotted-circle}** No |
+| [irker (IRC gateway)](irker.md)                           | Send IRC messages.                                                                           | **{dotted-circle}** No |
 | [Jenkins](../../../integration/jenkins.md)                | Run CI/CD pipelines with Jenkins.                                                            | **{check-circle}** Yes |
 | JetBrains TeamCity CI                                     | Run CI/CD pipelines with TeamCity.                                                           | **{check-circle}** Yes |
 | [Jira](jira.md)                                           | Use Jira as the issue tracker.                                                               | **{dotted-circle}** No |

locale/gitlab.pot

@@ -7988,6 +7988,9 @@ msgstr ""
 msgid "Collector hostname"
 msgstr ""
+msgid "Colorize messages"
+msgstr ""
+
 msgid "ComboSearch is not defined"
 msgstr ""
@@ -18122,6 +18125,42 @@ msgstr ""
 msgid "Invocations"
 msgstr ""
+msgid "IrkerService|Channels and users separated by whitespaces. %{recipients_docs_link}"
+msgstr ""
+
+msgid "IrkerService|Default IRC URI (optional)"
+msgstr ""
+
+msgid "IrkerService|How to enter channels or users?"
+msgstr ""
+
+msgid "IrkerService|Recipients"
+msgstr ""
+
+msgid "IrkerService|Send update messages to an irker server."
+msgstr ""
+
+msgid "IrkerService|Send update messages to an irker server. Before you can use this, you need to set up the irker daemon. %{docs_link}"
+msgstr ""
+
+msgid "IrkerService|Server host (optional)"
+msgstr ""
+
+msgid "IrkerService|Server port (optional)"
+msgstr ""
+
+msgid "IrkerService|URI to add before each recipient."
+msgstr ""
+
+msgid "IrkerService|irker (IRC gateway)"
+msgstr ""
+
+msgid "IrkerService|irker daemon hostname (defaults to localhost)."
+msgstr ""
+
+msgid "IrkerService|irker daemon port (defaults to 6659)."
+msgstr ""
+
 msgid "Is blocked by"
 msgstr ""

spec/features/projects/services/user_activates_irker_spec.rb

@@ -2,16 +2,16 @@
 
 require 'spec_helper'
 
-RSpec.describe 'User activates Irker (IRC gateway)' do
+RSpec.describe 'User activates irker (IRC gateway)' do
   include_context 'project service activation'
 
   it 'activates service', :js do
-    visit_project_integration('Irker (IRC gateway)')
+    visit_project_integration('irker (IRC gateway)')
     check('Colorize messages')
     fill_in('Recipients', with: 'irc://chat.freenode.net/#commits')
 
     click_test_then_save_integration(expect_test_to_fail: false)
 
-    expect(page).to have_content('Irker (IRC gateway) settings saved and active.')
+    expect(page).to have_content('irker (IRC gateway) settings saved and active.')
   end
 end

spec/features/projects/services/user_views_services_spec.rb

@@ -16,7 +16,7 @@
     expect(page).to have_content('Atlassian Bamboo')
     expect(page).to have_content('JetBrains TeamCity')
     expect(page).to have_content('Asana')
-    expect(page).to have_content('Irker (IRC gateway)')
+    expect(page).to have_content('irker (IRC gateway)')
     expect(page).to have_content('Packagist')
   end
 end