Add help for many options (#1540)

* Capitalize GitLab correctly in messages and docs

* Capitalize GitLab correctly in test data

* Capitalize GitLab correctly in error messages

* Capitalize correctly in messages

* Capitalize GitLab in test assertion

* Add apiTokenID help

* Add API level help

* Help for connection timeout

* Describe the ignore SSL certificate errors checkbox

* Describe the name field

* Describe the read timeout

* Describe URL field

* Add help for the authenticated end-pont checkbox

* Add global help (not visible from the UI)

* More help

* Add help for several trigger settings

* Add help for labels that force builds

* Add help for some of advanced trigger options

* Add help for cancel pending builds on merge request update

---------

Co-authored-by: Kris Stern <[email protected]>

.github/ISSUE_TEMPLATE.md

@@ -9,16 +9,16 @@
 ## Issue
 
 ### Context
-- **Gitlab plugin version**: X.Y.Z
-- **Gitlab version**: X.Y.Z
+- **GitLab plugin version**: X.Y.Z
+- **GitLab version**: X.Y.Z
 - **Jenkins version**: X.Y.Z
 - **Job type**: Pipeline, Freestyle, Matrix, etc.
 
 ### Logs & Traces
 
 _Please include any relevant log that could serve to better understand the source of your issue_
-For Jenkins Gitlab Plugin logs, follow instruction in [User Support section](https://github.com/jenkinsci/gitlab-plugin#user-support).
-For Gitlab logs, ask an administrator to provide you the relevant Gitlab logs.
+For Jenkins GitLab Plugin logs, follow instruction in [User Support section](https://github.com/jenkinsci/gitlab-plugin#user-support).
+For GitLab logs, ask an administrator to provide you the relevant GitLab logs.
 
 ### Problem description
 

CHANGELOG.md

@@ -30,8 +30,8 @@ ChangeLog
 * #951: Fix inability to trigger builds on accepted Merge Request
 * #1002: Fix that the plugin checks only global permissions instead of both global and project-level permissions
 * #1008: Fix NPE during commit status retrieval by gitlabCommitStatus step
-* #1012: Fix NPE if SCM revision is null (probably occurs only while using with Gitlab Branch Source Plugin)
-* #1014: Fix another NPE while using this plugin with Gitlab Branch Source Plugin
+* #1012: Fix NPE if SCM revision is null (probably occurs only while using with GitLab Branch Source Plugin)
+* #1014: Fix another NPE while using this plugin with GitLab Branch Source Plugin
 
 1.5.15
 =====================
@@ -149,7 +149,7 @@ ChangeLog
 * #532: Allow publishing a comment to the GitLab MR if the build result is 'unstable'
 * #543: Matrix/multi-configuration project support
 * #544: Add a button to clear the security token in build configuration
-* #559: Add a function to (re)set the Gitlab connections for bootstrapping new Jenkins installs
+* #559: Add a function to (re)set the GitLab connections for bootstrapping new Jenkins installs
 * #562: Fix issue #523 - Build result sent to Pipeline library repo instead of project repo
 
 1.4.5
@@ -186,7 +186,7 @@ ChangeLog
 * Breaking changes for some Pipeline jobs (see [migration guide](https://github.com/jenkinsci/gitlab-plugin/wiki/Migration-Guides) for more information)
 * Cleanup UI for GitLabPushTrigger
 * #201: customize notes for merge requsts
-* #168: MR Voting Broken after Gitlab 8.2
+* #168: MR Voting Broken after GitLab 8.2
 * #190: Add option to mark unstable builds as success in GitLab
 * #345: Configurable "Add note with build status on merge requests"
 * Add Notifier and workflow step for accepting a MR on success
@@ -224,12 +224,12 @@ ChangeLog
 =====================
 * #332: Find better fitting labels for the supported kind of GitLab credentials in global configuration
 * #261: Support [WIP] tag to prevent builds from triggering
-* #317: Retried builds are not marked immediately with Gitlab 8.1
+* #317: Retried builds are not marked immediately with GitLab 8.1
 * #306: GitLab [ci-skip] is ignored
 * #362: Allow to change build name submitted to GitLab
 * Catch client exceptions while retrieving the projectId from GitLab
 * #358: Null pointer exception when using 'rebuild open MRs' and GitLab 7.14
-* #364: gitlabCommitStatus: Gitlab in non-root location
+* #364: gitlabCommitStatus: GitLab in non-root location
 * #213: Trigger build by phrase in merge request note
 * #282: Authentication not required for /project end-point
 * #359: Git repositories in dockerized GitLab cannot be reached from Jenkins when using plugin-provided url parameters
@@ -251,7 +251,7 @@ ChangeLog
 * #311 Fix finding related commit of the build
 * #312 Fix setting MR IID
 * #319: Wrong username in Jenkins build description on push event
-* #322 Git push hook namespace compatibility for Gitlab pre ~v8.5
+* #322 Git push hook namespace compatibility for GitLab pre ~v8.5
 * #327 Fix to support NameSpace or ProjectName with dot in it
 * Update tests for new commit status publisher behavior
 * Use HTTP Get instead of HEAD to check for the existence of a commit as workaround for RESTEASY-1347

src/main/java/com/dabsquared/gitlabjenkins/util/CommitStatusUpdater.java

@@ -67,7 +67,7 @@ public static void updateCommitStatus(
                     gitLabBranchBuilds = retrieveGitlabProjectIds(build, environment);
                 }
             } catch (IOException | InterruptedException e) {
-                printf(listener, "Failed to get Gitlab Build list to update status: %s%n", e.getMessage());
+                printf(listener, "Failed to get GitLab Build list to update status: %s%n", e.getMessage());
             }
         }
 
@@ -106,13 +106,13 @@ public static void updateCommitStatus(
                 } catch (WebApplicationException | ProcessingException e) {
                     printf(
                             listener,
-                            "Failed to update Gitlab commit status for project '%s': %s%n",
+                            "Failed to update GitLab commit status for project '%s': %s%n",
                             gitLabBranchBuild.getProjectId(),
                             e.getMessage());
                     LOGGER.log(
                             Level.SEVERE,
                             String.format(
-                                    "Failed to update Gitlab commit status for project '%s'",
+                                    "Failed to update GitLab commit status for project '%s'",
                                     gitLabBranchBuild.getProjectId()),
                             e);
                 }
@@ -124,7 +124,7 @@ public static void updateCommitStatus(Run<?, ?> build, TaskListener listener, Bu
         try {
             updateCommitStatus(build, listener, state, name, null, null);
         } catch (IllegalStateException e) {
-            printf(listener, "Failed to update Gitlab commit status: %s%n", e.getMessage());
+            printf(listener, "Failed to update GitLab commit status: %s%n", e.getMessage());
         }
     }
 

src/main/java/com/dabsquared/gitlabjenkins/workflow/GitLabBranchBuild.java

@@ -74,7 +74,7 @@ public static class DescriptorImpl extends Descriptor<GitLabBranchBuild> {
         @NonNull
         @Override
         public String getDisplayName() {
-            return "Gitlab Branch Build";
+            return "GitLab Branch Build";
         }
     }
 }

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/config.jelly

@@ -44,7 +44,7 @@
     <f:entry title="${%Ignore WIP Merge Requests}" field="skipWorkInProgressMergeRequest">
       <f:checkbox default="true"/>
     </f:entry>
-    <f:entry title="Labels that forces builds if they are added (comma-separated)">
+    <f:entry title="Labels that launch a build if they are added (comma-separated)" help="/plugin/gitlab-plugin/help/help-labelsThatForcesBuildIfAdded.html">
       <f:textbox field="labelsThatForcesBuildIfAdded"/>
     </f:entry>
     <f:entry title="Set build description to build cause (eg. Merge request or Git Push)" field="setBuildDescription">

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-cancelPendingBuildsOnUpdate.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then pending builds will be canceled when a merge request is updated in the GitLab repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-ciSkip.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be skipped when a GitLab comment includes the text <code>ci-skip</code>.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-setBuildDescription.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build Jenkins description will be updated with the build cause.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-skipWorkInProgressMergeRequest.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be skipped when a GitLab merge request is a work in progress.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-triggerOnAcceptedMergeRequest.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be triggered when a merge request is accepted in the GitLab repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-triggerOnApprovedMergeRequest.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be triggered when a merge request is approved on the GitLab Enterprise Edition repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-triggerOnClosedMergeRequest.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be triggered when merge requests are closed in the GitLab repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-triggerOnMergeRequest.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be triggered when a merge request is created in the GitLab repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-triggerOnNoteRequest.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be triggered when a comment is added to the GitLab repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-triggerOnPush.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be triggered when new commits are pushed to the GitLab repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-triggerOnlyIfNewCommitsPushed.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be triggered when new commits are pushed to the GitLab repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-triggerOpenMergeRequestOnPush.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be triggered when changes are made to open merge requests in the GitLab repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help-triggerToBranchDeleteRequest.html

@@ -0,0 +1,3 @@
+<div>
+  If enabled, then the build will be triggered when a branch is deleted from the GitLab repository.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/GitLabPushTrigger/help.html

@@ -0,0 +1,3 @@
+<div>
+  Options for triggering Jenkins jobs based on GitLab events.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnection/config.jelly

@@ -3,14 +3,14 @@
     <f:entry title="${%Connection name}" field="name" description="${%A name for the connection}">
       <f:textbox/>
     </f:entry>
-    <f:entry title="${%Gitlab host URL}" field="url" description="${%The complete URL to the Gitlab server} (${%e.g. http://gitlab.mydomain.com})">
+    <f:entry title="${%GitLab host URL}" field="url" description="${%The complete URL to the GitLab server} (${%e.g. http://gitlab.mydomain.com})">
       <f:textbox />
     </f:entry>
-    <f:entry title="${%Credentials}" field="apiTokenId" description="${%API Token for accessing Gitlab}">
+    <f:entry title="${%Credentials}" field="apiTokenId" description="${%API Token for accessing GitLab}">
       <c:select/>
     </f:entry>
     <f:advanced>
-      <f:entry title="${%API-Level}" field="clientBuilderId" description="${%API Level for accessing Gitlab}">
+      <f:entry title="${%API-Level}" field="clientBuilderId" description="${%API Level for accessing GitLab}">
         <f:select default="autodetect"/>
       </f:entry>
       <f:entry title="${%Ignore SSL Certificate Errors}" field="ignoreCertificateErrors">

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnection/help-apiTokenId.html

@@ -0,0 +1,13 @@
+<div>
+  <p>
+  API token used by the GitLab plugin to access the GitLab API.
+  </p>
+  <p>
+  If a <a href="https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token">GitLab personal access token</a> is provided, GitLab will be accessed by Jenkins as the user that generated the personal access token.
+  If a <a href="https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#create-a-project-access-token">GitLab project access token</a> is provided, GitLab will be accessed by Jenkins at the project level.
+  If a <a href="https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html#create-a-group-access-token-using-ui">GitLab group access token</a> is provided, GitLab will be accessed by Jenkins at the group level, with access to all projects in the group.
+  </p>
+  <p>
+  Assign the <code>API</code> scope to the access token so that it can use the GitLab API.
+  </p>
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnection/help-clientBuilderId.html

@@ -0,0 +1,3 @@
+<div>
+  API level used to access GitLab
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnection/help-connectionTimeout.html

@@ -0,0 +1,3 @@
+<div>
+  Number of seconds to wait for the connection to GitLab to be completed.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnection/help-ignoreCertificateErrors.html

@@ -0,0 +1,5 @@
+<div>
+  If enabled, then errors related to the secure sockets layer (SSL) certificate validation will be ignored.
+  SSL certificate errors should generally not be ignored.
+  SSL certificates assure that the communications between Jenkins and GitLab is using an encrypted connection.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnection/help-name.html

@@ -0,0 +1,3 @@
+<div>
+  Name that will be used in Jenkins to refer to this GitLab connection. 
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnection/help-readTimeout.html

@@ -0,0 +1,3 @@
+<div>
+  Number of seconds that Jenkins will wait for data from the GitLab API before it reports a timeout.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnection/help-url.html

@@ -0,0 +1,4 @@
+<div>
+  URL of the GitLab server.
+  <code>https://gitlab.com</code> or <code>https://gitlab.example.com</code> are both examples of valid URLs for GitLab servers.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnection/help.html

@@ -0,0 +1,3 @@
+<div>
+  GitLab connection configuration for global connection settings.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnectionConfig/config.jelly

@@ -1,6 +1,6 @@
 <?jelly escape-by-default='true'?>
 <j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
-  <f:section title="Gitlab">
+  <f:section title="GitLab">
     <f:entry title="${%Enable authentication for '/project' end-point}" field="useAuthenticatedEndpoint">
       <f:checkbox  default="true"/>
     </f:entry>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnectionConfig/help-useAuthenticatedEndpoint.html

@@ -0,0 +1,9 @@
+<div>
+  <p>
+  Authentication on the <code>/project</code> end-point allows separate authentication credentials for each Jenkins job.
+  Separate credentials allow each Jenkins job to define their own token in the GitLab configuration section of the job definition.
+  </p>
+  <p>
+  The token generated in the Jenkins job needs to be pasted into the GitLab "Secret Token" field of the GitLab project webhook definition associated with that Jenkins job.
+  </p>
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/GitLabConnectionConfig/help.html

@@ -0,0 +1,3 @@
+<div>
+  GitLab connection definitions used by the GitLab plugin.
+</div>

src/main/resources/com/dabsquared/gitlabjenkins/connection/Messages.properties

@@ -1,7 +1,7 @@
-name.required=Gitlab connection name required.
+name.required=GitLab connection name required.
 name.exists=GitLab connection name "{0}" already exists
-url.required=Gitlab host URL required.
-apiToken.required=API Token for Gitlab access required
+url.required=GitLab host URL required.
+apiToken.required=API Token for GitLab access required
 connectionTimeout.required=Connection timeout is required
 readTimeout.required=Read timeout is required
 connection.success=Success

src/main/webapp/help/help-labelsThatForcesBuildIfAdded.html

@@ -0,0 +1,5 @@
+<div>
+  <div>
+    A comma separated list of labels that will launch a Jenkins build if the label is assigned in GitLab.
+  </div>
+</div>

src/main/webapp/help/help-pendingBuildName.html

@@ -1,8 +1,8 @@
 <div>
   <div>
     <p>Applicable only for pipelines.</p>
-    <p>When filled, a 'pending' build status with the given build name is published to Gitlab when the pipeline is
+    <p>When filled, a 'pending' build status with the given build name is published to GitLab when the pipeline is
       triggered. Further status updates should be defined in pipeline steps.</p>
-    <p>For other types of jobs the build name is taken from 'Publish build status to Gitlab commit' post-build action.</p>
+    <p>For other types of jobs the build name is taken from 'Publish build status to GitLab commit' post-build action.</p>
   </div>
 </div>

src/test/java/com/dabsquared/gitlabjenkins/connection/GitLabConnectionConfigAsCodeTest.java

@@ -40,7 +40,7 @@ public void configure_gitlab_api_token() throws Exception {
                 (GitLabApiToken) gitLabCredential.getCredentials().get(0);
         assertEquals("gitlab_token", apiToken.getId());
         assertEquals("qwertyuiopasdfghjklzxcvbnm", apiToken.getApiToken().getPlainText());
-        assertEquals("Gitlab Token", apiToken.getDescription());
+        assertEquals("GitLab Token", apiToken.getDescription());
     }
 
     @Test

src/test/java/com/dabsquared/gitlabjenkins/publisher/GitLabCommitStatusPublisherTest.java

@@ -267,7 +267,7 @@ public void running_failToUpdate() throws UnsupportedEncodingException {
         assertThat(
                 outputStream.toString(),
                 CoreMatchers.containsString(
-                        "Failed to update Gitlab commit status for project 'test/project': HTTP 403 Forbidden"));
+                        "Failed to update GitLab commit status for project 'test/project': HTTP 403 Forbidden"));
     }
 
     private void prebuildAndVerify(AbstractBuild build, BuildListener listener, HttpRequest... requests) {

src/test/resources/com/dabsquared/gitlabjenkins/connection/global-config.yml

@@ -6,7 +6,7 @@ credentials:
               scope: SYSTEM
               id: gitlab_token
               apiToken: "${BIND_TOKEN}"
-              description: "Gitlab Token"
+              description: "GitLab Token"
 unclassified:
   gitlabconnectionconfig:
     useAuthenticatedEndpoint: true

src/test/resources/com/dabsquared/gitlabjenkins/webhook/ActionResolverTest_postNote.json

@@ -7,13 +7,13 @@
   },
   "project_id": 5,
   "project":{
-    "name":"Gitlab Test",
+    "name":"GitLab Test",
     "description":"Aut reprehenderit ut est.",
     "web_url":"http://example.com/gitlab-org/gitlab-test",
     "avatar_url":null,
     "git_ssh_url":"[email protected]:gitlab-org/gitlab-test.git",
     "git_http_url":"http://example.com/gitlab-org/gitlab-test.git",
-    "namespace":"Gitlab Org",
+    "namespace":"GitLab Org",
     "visibility_level":10,
     "path_with_namespace":"gitlab-org/gitlab-test",
     "default_branch":"master",
@@ -23,7 +23,7 @@
     "http_url":"http://example.com/gitlab-org/gitlab-test.git"
   },
   "repository":{
-    "name": "Gitlab Test",
+    "name": "GitLab Test",
     "url": "http://localhost/gitlab-org/gitlab-test.git",
     "description": "Aut reprehenderit ut est.",
     "homepage": "http://example.com/gitlab-org/gitlab-test"
@@ -63,13 +63,13 @@
     "position": 0,
     "locked_at": null,
     "source":{
-      "name":"Gitlab Test",
+      "name":"GitLab Test",
       "description":"Aut reprehenderit ut est.",
       "web_url":"http://example.com/gitlab-org/gitlab-test",
       "avatar_url":null,
       "git_ssh_url":"[email protected]:gitlab-org/gitlab-test.git",
       "git_http_url":"http://example.com/gitlab-org/gitlab-test.git",
-      "namespace":"Gitlab Org",
+      "namespace":"GitLab Org",
       "visibility_level":10,
       "path_with_namespace":"gitlab-org/gitlab-test",
       "default_branch":"master",
@@ -79,13 +79,13 @@
       "http_url":"http://example.com/gitlab-org/gitlab-test.git"
     },
     "target": {
-      "name":"Gitlab Test",
+      "name":"GitLab Test",
       "description":"Aut reprehenderit ut est.",
       "web_url":"http://example.com/gitlab-org/gitlab-test",
       "avatar_url":null,
       "git_ssh_url":"[email protected]:gitlab-org/gitlab-test.git",
       "git_http_url":"http://example.com/gitlab-org/gitlab-test.git",
-      "namespace":"Gitlab Org",
+      "namespace":"GitLab Org",
       "visibility_level":10,
       "path_with_namespace":"gitlab-org/gitlab-test",
       "default_branch":"master",