Improve chatops help outputimprove-chatops-help

This improves the output produced when running an unknown command,
running the "help" command, and when trying to run a command you are not
allowed to run. The new help output includes links to the project of the
chatops integration, and a link to the chatops documentation.

5 files changed, 75 insertions, 25 deletions

diff --git a/lib/gitlab/slash_commands/application_help.rb b/lib/gitlab/slash_commands/application_help.rb
index 0ea7554ba64..1a92346be15 100644
--- a/lib/gitlab/slash_commands/application_help.rb
+++ b/lib/gitlab/slash_commands/application_help.rb
@@ -3,12 +3,15 @@
 module Gitlab
   module SlashCommands
     class ApplicationHelp < BaseCommand
-      def initialize(params)
+      def initialize(project, params)
+        @project = project
         @params = params
       end
 
       def execute
-        Gitlab::SlashCommands::Presenters::Help.new(commands).present(trigger, params[:text])
+        Gitlab::SlashCommands::Presenters::Help
+          .new(project, commands)
+          .present(trigger, params[:text])
       end
 
       private
diff --git a/lib/gitlab/slash_commands/command.rb b/lib/gitlab/slash_commands/command.rb
index 7c963fcf38a..45c34d8b86b 100644
--- a/lib/gitlab/slash_commands/command.rb
+++ b/lib/gitlab/slash_commands/command.rb
@@ -21,7 +21,7 @@ module Gitlab
           if command.allowed?(project, current_user)
             command.new(project, chat_name, params).execute(match)
           else
-            Gitlab::SlashCommands::Presenters::Access.new.access_denied
+            Gitlab::SlashCommands::Presenters::Access.new.access_denied(project)
           end
         else
           Gitlab::SlashCommands::Help.new(project, chat_name, params)
diff --git a/lib/gitlab/slash_commands/help.rb b/lib/gitlab/slash_commands/help.rb
index dbe15baa3d7..3eff64192ab 100644
--- a/lib/gitlab/slash_commands/help.rb
+++ b/lib/gitlab/slash_commands/help.rb
@@ -19,7 +19,9 @@ module Gitlab
       end
 
       def execute(commands, text)
-        Gitlab::SlashCommands::Presenters::Help.new(commands).present(trigger, text)
+        Gitlab::SlashCommands::Presenters::Help
+          .new(project, commands)
+          .present(trigger, text)
       end
 
       def trigger
diff --git a/lib/gitlab/slash_commands/presenters/access.rb b/lib/gitlab/slash_commands/presenters/access.rb
index fa163cb098e..b1bfaa6cb59 100644
--- a/lib/gitlab/slash_commands/presenters/access.rb
+++ b/lib/gitlab/slash_commands/presenters/access.rb
@@ -4,8 +4,15 @@ module Gitlab
   module SlashCommands
     module Presenters
       class Access < Presenters::Base
-        def access_denied
-          ephemeral_response(text: "Whoops! This action is not allowed. This incident will be [reported](https://xkcd.com/838/).")
+        def access_denied(project)
+          ephemeral_response(text: <<~MESSAGE)
+            You are not allowed to perform the given chatops command. Most
+            likely you do not have access to the GitLab project for this chatops
+            integration.
+
+            The GitLab project for this chatops integration can be found at
+            #{url_for(project)}.
+          MESSAGE
         end
 
         def not_found
@@ -22,20 +29,6 @@ module Gitlab
 
           ephemeral_response(text: message)
         end
-
-        def unknown_command(commands)
-          ephemeral_response(text: help_message(trigger))
-        end
-
-        private
-
-        def help_message(trigger)
-          header_with_list("Command not found, these are the commands you can use", full_commands(trigger))
-        end
-
-        def full_commands(trigger)
-          @resource.map { |command| "#{trigger} #{command.help_message}" }
-        end
       end
     end
   end
diff --git a/lib/gitlab/slash_commands/presenters/help.rb b/lib/gitlab/slash_commands/presenters/help.rb
index 480d7aa6a30..5421b0b9a84 100644
--- a/lib/gitlab/slash_commands/presenters/help.rb
+++ b/lib/gitlab/slash_commands/presenters/help.rb
@@ -4,6 +4,11 @@ module Gitlab
   module SlashCommands
     module Presenters
       class Help < Presenters::Base
+        def initialize(project, commands)
+          @project = project
+          @commands = commands
+        end
+
         def present(trigger, text)
           ephemeral_response(text: help_message(trigger, text))
         end
@@ -11,17 +16,64 @@ module Gitlab
         private
 
         def help_message(trigger, text)
-          return "No commands available :thinking_face:" unless @resource.present?
+          unless @commands.present?
+            return <<~MESSAGE
+              This chatops integration does not have any commands that can be
+              executed.
+
+              #{footer}
+            MESSAGE
+          end
 
           if text.start_with?('help')
-            header_with_list("Available commands", full_commands(trigger))
+            <<~MESSAGE
+              #{full_commands_message(trigger)}
+
+              #{help_footer}
+            MESSAGE
           else
-            header_with_list("Unknown command, these commands are available", full_commands(trigger))
+            <<~MESSAGE
+              The specified command is not valid.
+
+              #{full_commands_message(trigger)}
+
+              #{help_footer}
+            MESSAGE
           end
         end
 
-        def full_commands(trigger)
-          @resource.map { |command| "#{trigger} #{command.help_message}" }
+        def help_footer
+          <<~MESSAGE
+            *Project*
+
+            The GitLab project for this chatops integration can be found at
+            #{url_for(@project)}.
+
+            *Documentation*
+
+            For more information about GitLab chatops, refer to its
+            documentation: https://docs.gitlab.com/ce/ci/chatops/README.html.
+          MESSAGE
+        end
+
+        def full_commands_message(trigger)
+          list = @commands
+            .map { |command| "#{trigger} #{command.help_message}" }
+            .join("\n")
+
+          <<~MESSAGE
+            *Available commands*
+
+            The following commands are available for this chatops integration:
+
+            #{list}
+
+            If available, the `run` command is used for running GitLab CI jobs
+            defined in this project's `.gitlab-ci.yml` file. For example, if a
+            job called "help" is defined you can run it like so:
+
+            `#{trigger} run help`
+          MESSAGE
         end
       end
     end