Add documentation for SlackNotification plugin

src/lib/Hydra/Plugin/SlackNotification.pm

@@ -7,6 +7,53 @@ use LWP::UserAgent;
 use Hydra::Helper::CatalystUtils;
 use JSON;
 
+=head1 NAME
+
+SlackNotification - hydra-notify plugin for sending Slack notifications about
+build results
+
+=head1 DESCRIPTION
+
+This plugin reports build statuses to various Slack channels. One can configure
+which builds are reported to which channels, and whether reports should be on
+state change (regressions and improvements), or for each build.
+
+=head1 CONFIGURATION
+
+The module is configured using the C<slack> block in Hydra's config file. There
+can be multiple such blocks in the config file, each configuring different (or
+even the same) set of builds and how they report to Slack channels.
+
+The following entries are recognized in the C<slack> block:
+
+=over 4
+
+=item jobs
+
+A pattern for job names. All builds whose job name matches this pattern will
+emit a message to the designated Slack channel (see C<url>). The pattern will
+match the whole name, thus leaving this field empty will result in no
+notifications being sent. To match on all builds, use C<.*>.
+
+=item url
+
+The URL to a L<Slack incoming webhook|https://api.slack.com/messaging/webhooks>.
+
+Slack administrators have to prepare one incoming webhook for each channel. This
+URL should be treated as secret, as anyone knowing the URL could post a message
+to the Slack workspace (or more precisely, the channel behind it).
+
+=item force
+
+(Optional) An I<integer> indicating whether to report on every build or only on
+changes in the status. If not provided, defaults to 0, that is, sending reports
+only when build status changes from success to failure, and vice-versa. Any
+other value results in reporting on every build.
+
+=back
+
+=cut
+
 sub isEnabled {
     my ($self) = @_;
     return defined $self->{config}->{slack};
@@ -44,9 +91,10 @@ sub buildFinished {
         my $jobName = showJobName $b;
 
         foreach my $channel (@config) {
-            my $force = $channel->{force};
             next unless $jobName =~ /^$channel->{jobs}$/;
 
+            my $force = $channel->{force};
+
             # If build is cancelled or aborted, do not send email.
             next if ! $force && ($b->buildstatus == 4 || $b->buildstatus == 3);