[JENKINS-43507] Add help files and tidy up misc code changes

src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMSource.java

@@ -962,26 +962,27 @@ public SCMRevision create(@NonNull PullRequestSCMHead head,
         }
     }
 
-    private void updateCollaboratorNames(@NonNull TaskListener listener, @CheckForNull StandardCredentials credentials,
-                                         @NonNull GHRepository ghRepository)
+    @NonNull
+    private Set<String> updateCollaboratorNames(@NonNull TaskListener listener, @CheckForNull StandardCredentials credentials,
+                                                @NonNull GHRepository ghRepository)
             throws IOException {
         if (credentials == null && (apiUri == null || GITHUB_URL.equals(apiUri))) {
             // anonymous access to GitHub will never get list of collaborators and will
             // burn an API call, so no point in even trying
             listener.getLogger().println("Anonymous cannot query list of collaborators, assuming none");
-            collaboratorNames = Collections.emptySet();
+            return collaboratorNames = Collections.emptySet();
         } else {
             try {
-                collaboratorNames = new HashSet<>(ghRepository.getCollaboratorNames());
+                return collaboratorNames = new HashSet<>(ghRepository.getCollaboratorNames());
             } catch (FileNotFoundException e) {
                 // not permitted
                 listener.getLogger().println("Not permitted to query list of collaborators, assuming none");
-                collaboratorNames = Collections.emptySet();
+                return collaboratorNames = Collections.emptySet();
             } catch (HttpException e) {
                 if (e.getResponseCode() == HttpServletResponse.SC_UNAUTHORIZED
                         || e.getResponseCode() == HttpServletResponse.SC_NOT_FOUND) {
                     listener.getLogger().println("Not permitted to query list of collaborators, assuming none");
-                    collaboratorNames = Collections.emptySet();
+                    return collaboratorNames = Collections.emptySet();
                 } else {
                     throw e;
                 }
@@ -1808,11 +1809,10 @@ public LazyContributorNames(GitHubSCMSourceRequest request,
         @Override
         protected Set<String> create() {
             try {
-                updateCollaboratorNames(listener, credentials, repo);
+                return updateCollaboratorNames(listener, credentials, repo);
             } catch (IOException e) {
                 throw new WrappedException(e);
             }
-            return collaboratorNames;
         }
     }
 

src/main/java/org/jenkinsci/plugins/github_branch_source/PullRequestSCMHead.java

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  *
- * Copyright 2016 CloudBees, Inc.
+ * Copyright 2016-2017 CloudBees, Inc.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

src/main/java/org/jenkinsci/plugins/github_branch_source/PullRequestSCMRevision.java

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  *
- * Copyright 2016 CloudBees, Inc.
+ * Copyright 2016-2017 CloudBees, Inc.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

src/main/java/org/jenkinsci/plugins/github_branch_source/PullRequestSource.java

@@ -1,3 +1,26 @@
+/*
+ * The MIT License
+ *
+ * Copyright 2016-2017 CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package org.jenkinsci.plugins.github_branch_source;
 
 /**

src/main/resources/org/jenkinsci/plugins/github_branch_source/BranchDiscoveryTrait/help-strategyId.html

@@ -0,0 +1,20 @@
+<div>
+    Determines which branches are discovered.
+    <dl>
+        <dt>Exclude branches that are also filed as PRs</dt>
+        <dd>
+            If you are discovering origin pull requests, it may not make sense to discover the same changes both as a
+            pull request and as a branch.
+        </dd>
+        <dt>Only branches that are also filed as PRs</dt>
+        <dd>
+            This option exists to preserve legacy behaviour when upgrading from older versions of the plugin.
+            NOTE: If you have an actual use case for this option please file a pull request against this text.
+        </dd>
+        <dt>All branches</dt>
+        <dd>
+            Ignores whether the branch is also filed as a pull request and instead discovers all branches on the
+            origin repository.
+        </dd>
+    </dl>
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/BranchDiscoveryTrait/help.html

@@ -0,0 +1,3 @@
+<div>
+    Discovers branches on the repository.
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/ForkPullRequestDiscoveryTrait/help-strategyId.html

@@ -0,0 +1,15 @@
+<div>
+    Determines how pull requests are discovered:
+    <ul>
+        <li>Discover each pull request once with the discovered revision corresponding to the result of merging with the
+            current revision of the target branch
+        </li>
+        <li>Discover each pull request once with the discovered revision corresponding to the pull request head revision
+            without merging
+        </li>
+        <li>Discover each pull request twice. The first discovered revision corresponds to the result of merging with
+            the current revision of the target branch in each scan. The second parallel discovered revision corresponds
+            to the pull request head revision without merging
+        </li>
+    </ul>
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/ForkPullRequestDiscoveryTrait/help-trust.html

@@ -0,0 +1,35 @@
+<div>
+    <p>
+        One of the great powers of pull requests is that anyone with read access to a repository can fork it, commit
+        some changes to their fork and then create a pull request against the original repository with their changes.
+        There are some files stored in source control that are important. For example, a <code>Jenkinsfile</code>
+        may contain configuration details to sandbox pull requests in order to mitigate against malicious pull requests.
+        In order to protect against a malicious pull request itself modifying the <code>Jenkinsfile</code> to remove
+        the protections, you can define the trust policy for pull requests from forks.
+    </p>
+    <p>
+        Other plugins can extend the available trust policies. The default policies are:
+    </p>
+    <dl>
+        <dt>Nobody</dt>
+        <dd>
+            Pull requests from forks will all be treated as untrusted. This means that where Jenkins requires a
+            trusted file (e.g. <code>Jenkinsfile</code>) the contents of that file will be retrieved from the
+            target branch on the origin repository and not from the pull request branch on the fork repository.
+        </dd>
+        <dt>Contributors</dt>
+        <dd>
+            Pull requests from <a href="https://developer.github.com/v3/repos/collaborators/">collaborators</a>
+            to the origin repository will be treated as trusted, all other pull requests from fork repositories
+            will be treated as untrusted..
+            Note that if credentials used by Jenkins for scanning the repository does not have permission to
+            query the list of contributors to the origin repository then only the origin account will be treated
+            as trusted - i.e. this will fall back to <code>Nobody</code>.
+        </dd>
+        <dt>Everyone</dt>
+        <dd>
+            All pull requests from forks will be treated as trusted. <strong>NOTE:</strong> this option can be dangerous
+            if used on a public repository hosted on Bitbucket Cloud.
+        </dd>
+    </dl>
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/ForkPullRequestDiscoveryTrait/help.html

@@ -0,0 +1,3 @@
+<div>
+    Discovers pull requests where the origin repository is a fork of the target repository.
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigator/help-apiUri.html

@@ -0,0 +1,4 @@
+<div>
+    The server to connect to. The list of servers is configured in the <strong>Manage Jenkins » Configure
+    Jenkins › GitHub Enterprise Servers</strong> screen.
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigator/help-traits.html

@@ -0,0 +1,16 @@
+<div>
+    The behaviours control what is discovered from the GitHub server. The behaviours are grouped into a number
+    of categories:
+    <dl>
+        <dt>Repository</dt>
+        <dd>These behaviours determine what repositories get discovered. Only repositories that have at least one
+            discovered branch / pull request can themselves be discovered.
+        </dd>
+        <dt>Within repository</dt>
+        <dd>These behaviours determine what gets discovered within each repository. <strong>If you do not configure
+            at least one discovery behaviour then nothing will be found!</strong></dd>
+        <dt>General</dt>
+        <dd>These behaviours affect the configuration of each discovered branch / pull request. 
+        </dd>
+    </dl>
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/GitHubSCMSource/help-apiUri.html

@@ -0,0 +1,4 @@
+<div>
+    The server to connect to. The list of servers is configured in the <strong>Manage Jenkins » Configure
+    Jenkins › GitHub Enterprise Servers</strong> screen.
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/GitHubSCMSource/help-repository.html

@@ -0,0 +1,3 @@
+<div>
+    The repository to scan.
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/GitHubSCMSource/help-traits.html

@@ -0,0 +1,12 @@
+<div>
+    The behaviours control what is discovered from the GitHub repository. The behaviours are grouped into a number
+    of categories:
+    <dl>
+        <dt>Within repository</dt>
+        <dd>These behaviours determine what gets discovered. <strong>If you do not configure at least one discovery
+            behaviour then nothing will be found!</strong></dd>
+        <dt>General</dt>
+        <dd>These behaviours affect the configuration of each discovered branch / pull request.
+        </dd>
+    </dl>
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/OriginPullRequestDiscoveryTrait/help-strategyId.html

@@ -0,0 +1,15 @@
+<div>
+    Determines how pull requests are discovered:
+    <ul>
+        <li>Discover each pull request once with the discovered revision corresponding to the result of merging with the
+            current revision of the target branch
+        </li>
+        <li>Discover each pull request once with the discovered revision corresponding to the pull request head revision
+            without merging
+        </li>
+        <li>Discover each pull request twice. The first discovered revision corresponds to the result of merging with
+            the current revision of the target branch in each scan. The second parallel discovered revision corresponds
+            to the pull request head revision without merging
+        </li>
+    </ul>
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/OriginPullRequestDiscoveryTrait/help.html

@@ -0,0 +1,3 @@
+<div>
+    Discovers pull requests where the origin repository is the same as the target repository.
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/SSHCheckoutTrait/help-credentialsId.html

@@ -0,0 +1,3 @@
+<div>
+    Credentials used to check out sources. Must be a SSH key based credential.
+</div>

src/main/resources/org/jenkinsci/plugins/github_branch_source/SSHCheckoutTrait/help.html

@@ -0,0 +1,9 @@
+<div>
+    By default the discovered branches / pull requests will all use the same username / password credentials
+    that were used for discovery when checking out sources. This means that the checkout will be using the
+    <code>https://</code> protocol for the Git repository.
+    <p>
+        This behaviour allows you to select the SSH private key to be used for checking out sources, which will
+        consequently force the checkout to use the <code>ssh://</code> protocol.
+    </p>
+</div>