Improve webhooks user and trait documentation (#923)

Author: nfalco79

docs/USER_GUIDE.adoc

@@ -89,17 +89,26 @@ allows to trigger builds on branches and pull requests just when a new commit is
 service to listen to these webhook requests and acts accordingly by triggering a new reindex and finally
 triggering builds on matching branches or pull requests.
 
-Go to "Manage Jenkins" / "Configure System" and locate _Bitbucket Endpoints_. For every endpoint where you want webhooks registered automatically,
+Go to "Manage Jenkins" / "System" and locate _Bitbucket Endpoints_. For every endpoint where you want webhooks registered automatically,
 check "Manage hooks" and select a "Credential" with enough access to add webhooks to repositories. Since the Credential is used at the system level,
 it can be a System scoped credential, which will restrict its usage from Pipelines.
+You can setup a custom Jenkins URL to be used as callback URL by the webhooks.
+
+For Bitbucket Server only it is possible chose which webhooks implementation server side to use:
+
+- Native implementation will configure the webhooks provided by default with the Server, so it will always be available.
+
+- Plugin implementation relies on the configuration available via specific APIs provided by the https://marketplace.atlassian.com/apps/1215474/post-webhooks-for-bitbucket?tab=overview&hosting=datacenter[Post Webhooks for Bitbucket] plugin itself. To get it worked plugin must be already pre-installed on the server instance. This provider allows custom settings managed by the _ignore committers_ trait. _Note: This specific implementation will be moved to an individual repository as soon as https://issues.jenkins.io/browse/JENKINS-74913[JENKINS-74913] is implemented._
+
+image::images/screenshot-14.png[scaledwidth=90%]
 
 For both Bitbucket _Multibranch Pipelines_ and _Organization folders_ there is an "Override hook management" behavior
 to opt out or adjust system-wide settings.
 
 image::images/screenshot-4.png[scaledwidth=90%]
 
 IMPORTANT: In order to have the auto-registering process working fine the Jenkins base URL must be
-properly configured in _Manage Jenkins_ » _Configure System_
+properly configured in _Manage Jenkins_ » _System_
 
 [id=bitbucket-creds-config]
 == Credentials configuration
@@ -173,4 +182,4 @@ In case of slow network, you can increase socket timeout using the link:https://
 [source,groovy]
 ----
 System.setProperty("http.socket.timeout", "300") // 5 minutes
-----
+----

docs/images/screenshot-14.png

@@ -129,7 +129,7 @@ private static void createStatus(@NonNull Run<?, ?> build, @NonNull TaskListener
             statusDescription = StringUtils.defaultIfBlank(buildDescription, "This commit looks good.");
             state = BitbucketBuildStatus.Status.SUCCESSFUL;
         } else if (Result.UNSTABLE.equals(result)) {
-            statusDescription = StringUtils.defaultIfBlank(buildDescription, "This commit has test failures.");
+            statusDescription = StringUtils.defaultIfBlank(buildDescription, "This commit may have some failing tests.");
             if (context.sendSuccessNotificationForUnstableBuild()) {
                 state = BitbucketBuildStatus.Status.SUCCESSFUL;
             } else {
@@ -182,11 +182,11 @@ private static void sendNotifications(BitbucketSCMSource source, Run<?, ?> build
         if (sourceContext.notificationsDisabled()) {
             return;
         }
-        SCMRevision r = SCMRevisionAction.getRevision(source, build);
-        if (r == null) {
+        SCMRevision rev = SCMRevisionAction.getRevision(source, build);
+        if (rev == null) {
             return;
         }
-        String hash = getHash(r);
+        String hash = getHash(rev);
         if (hash == null) {
             return;
         }
@@ -196,14 +196,14 @@ private static void sendNotifications(BitbucketSCMSource source, Run<?, ?> build
 
         String key;
         BitbucketApi bitbucket;
-        if (r instanceof PullRequestSCMRevision) {
+        if (rev instanceof PullRequestSCMRevision) {
             listener.getLogger().println("[Bitbucket] Notifying pull request build result");
-            PullRequestSCMHead head = (PullRequestSCMHead) r.getHead();
+            PullRequestSCMHead head = (PullRequestSCMHead) rev.getHead();
             key = getBuildKey(build, head.getOriginName(), shareBuildKeyBetweenBranchAndPR);
             bitbucket = source.buildBitbucketClient(head);
         } else {
             listener.getLogger().println("[Bitbucket] Notifying commit build result");
-            key = getBuildKey(build, r.getHead().getName(), shareBuildKeyBetweenBranchAndPR);
+            key = getBuildKey(build, rev.getHead().getName(), shareBuildKeyBetweenBranchAndPR);
             bitbucket = source.buildBitbucketClient();
         }
         createStatus(build, listener, bitbucket, key, hash);

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/BitbucketBuildStatusNotifications.java

@@ -35,7 +35,7 @@ SSHCheckoutTrait.useAgentKey=- use build agent''s key -
 WebhookRegistrationTrait.disableHook=Disable hook management
 WebhookRegistrationTrait.displayName=Override hook management
 WebhookRegistrationTrait.useItemHook=Use item credentials for hook management
-WebhookConfigurationTrait.displayName=Set ignored committers
+WebhookConfigurationTrait.displayName=Configure committers to be ignored by the webhook
 PullRequestSCMHead.Pronoun=Pull Request
 BranchSCMHead.Pronoun=Branch
 BitbucketTagSCMHead.Pronoun=Tag

src/main/resources/com/cloudbees/jenkins/plugins/bitbucket/Messages.properties

@@ -1,6 +1,6 @@
 <?jelly escape-by-default='true'?>
 <j:jelly xmlns:j="jelly:core" xmlns:f="/lib/form">
-  <f:entry title="${%Ignore committers}" field="committersToIgnore">
+  <f:entry title="${%Prevents webhook from users ids}" field="committersToIgnore">
     <f:textbox/>
   </f:entry>
 </j:jelly>

src/main/resources/com/cloudbees/jenkins/plugins/bitbucket/WebhookConfigurationTrait/config.jelly

@@ -1,9 +1,12 @@
 <div>
     <p>
-        Sets the value for committersToIgnore in the Bitbucket Webhook. Value should be a comma separated string.
+        Comma separated list of user ids in bitbucket to ignore commits from for triggering the webhook.
     </p>
     <p>
-        committerToIgnore is used to prevent triggering Jenkins builds when commits by certain users
-        are made.
+        committerToIgnore is used exclusively by the "Post Webhooks for Bitbucket" plugin to prevent a server notification
+        from being sent to the Jenkins instance to avoid triggering builds when commits are made by certain users.
     </p>
-</div>
+    <p>
+        References could be found <a href="https://help.moveworkforward.com/BPW/how-to-manage-configurations-using-post-webhooks-f#HowtomanageconfigurationsusingPostWebhooksforBitbucketAPIs?-UpdateapostwebhookbyID">here</a>.
+    </p>
+</div>

src/main/resources/com/cloudbees/jenkins/plugins/bitbucket/WebhookConfigurationTrait/help.html

@@ -2,7 +2,7 @@
     Determines which Webhook implementation is to be used:
     <dl>
         <dt>Plugin</dt>
-        <dd>The third party Webhook implementation provided by a plugin.</dd>
+        <dd>The third party Webhook implementation provided by a <a href="https://marketplace.atlassian.com/apps/1215474/post-webhooks-for-bitbucket?tab=overview&hosting=datacenter">Post Webhooks for Bitbucket</a> plugin.</dd>
         <dd>Please note cloning from mirror is not supported with this implementation.</dd>
 
         <dt>Native</dt>