[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>