Improve wording (#493)

* Improve wording

* Consistent naming for the plugin and Bitbucket

* Rearrange Bitbucket Server 7.x changes description

Co-authored-by: Liam Newman <bitwiseman@gmail.com>

Co-authored-by: Liam Newman <bitwiseman@gmail.com>

README.adoc

@@ -1,18 +1,17 @@
-== BitBucket Branch Source Plugin
+== Bitbucket Branch Source Plugin
 
 image:https://img.shields.io/jenkins/plugin/v/cloudbees-bitbucket-branch-source["Jenkins Plugin", link="https://plugins.jenkins.io/cloudbees-bitbucket-branch-source"]
 image:https://img.shields.io/jenkins/plugin/i/cloudbees-bitbucket-branch-source?color=blue["Jenkins Plugin Installs", link="https://plugins.jenkins.io/cloudbees-bitbucket-branch-source"]
 image:https://img.shields.io/github/release/jenkinsci/bitbucket-branch-source-plugin.svg?label=changelog["Changelog", link="https://github.com/jenkinsci/bitbucket-branch-source-plugin/releases/latest"]
 image:https://badges.gitter.im/Join%20Chat.svg["Join the chat",link="https://gitter.im/jenkinsci/bitbucket-branch-source-plugin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]
 
-
 === User Guide
 
 link:./docs/USER_GUIDE.adoc[Browse the user guide here]
 
 === Notes
 
-* Unlike GitHub, in BitBucket, https://bitbucket.org/site/master/issues/4828/team-admins-dont-have-read-access-to-forks[team admins do not have access to forks].
+* Unlike GitHub, in Bitbucket, https://bitbucket.org/site/master/issues/4828/team-admins-dont-have-read-access-to-forks[team admins do not have access to forks].
 This means that when you have a private repository, or a private fork of a public repository, the team admin will not be able to see the PRs within the fork.
 
 === How-to run and test with Bitbucket Server locally

docs/USER_GUIDE.adoc

@@ -1,20 +1,21 @@
-= CloudBees Bitbucket Branch Source plugin
+= Bitbucket Branch Source Plugin
 
 [IMPORTANT]
 =====================================================================
-On March 5th, 2020, link:https://confluence.atlassian.com/bitbucketserver/bitbucket-server-7-0-release-notes-990546638.html[Atlassian releases Bitbucket Server 7] which removed some undocumented features with regards to pull requests.
+On March 5th, 2020, link:https://confluence.atlassian.com/bitbucketserver/bitbucket-server-7-0-release-notes-990546638.html[Atlassian releases Bitbucket Server 7] which removed some undocumented features related to pull requests.
 
-. BitBucket Server Pipeline jobs can no longer perform a lightweight checkout of the Jenkinsfile if you are using the merge strategy for builds.
-.. BitBucket Server no longer stores the merged result of a PR to link:https://jira.atlassian.com/browse/BSERV-12284?focusedCommentId=2389584&[improve performance]
-.. BitBucket Server Pipeline jobs will automatically fallback to heavyweight checkout
-. BitBucket Server 7.x no longer automatically creates the required refs for pull requests
-.. For Bitbucket Server Pipeline jobs to function for pull requests on BitBucket Server 7.x you need to enable "Call Changes api" option in the plugin configuration
+. With Bitbucket Server 7.x, Jenkins Pipeline jobs can no longer perform a lightweight checkout of the `Jenkinsfile` if you are using the merge strategy for builds.
+.. This is due to Bitbucket Server 7.x no longer storing the merge commit for PRs to `refs/pull-requests/*/merge` which was a prerequisite for lightweight checkout.
+.. Bitbucket Server Pipeline jobs will automatically fall back to heavyweight checkout.
+.. link:https://jira.atlassian.com/browse/BSERV-12284?focusedCommentId=2389584&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-2389584[Atlassian has explained their reasons for making this change] and has made it clear they will not be re-adding this behavior.
+. For Jenkins Pipeline jobs to function for pull requests on Bitbucket Server 7.x, you need to enable "Call Changes api" option in the plugin configuration.
+.. Bitbucket Server 7.x no longer automatically creates the required refs for pull requests. Calls to this new API are required to trigger ref creation.
 
 =====================================================================
 
 [id=bitbucket-sect-intro]
 
-_CloudBees Bitbucket Branch Source plugin_ (_Bitbucket plugin_ up now) allows use of Bitbucket Cloud and Server
+_Bitbucket Branch Source plugin_ allows use of Bitbucket Cloud and Server
 as a multi-branch project source in two different ways:
 
  * *Single repository source*: automatic creation of jobs for branches and pull requests in a specific repository.
@@ -23,9 +24,9 @@ as a multi-branch project source in two different ways:
  IMPORTANT: This plugin is not compatible with versions of Bitbucket Server previous to 4.0.
 
 [id=bitbucket-server-7]
-== BitBucket Server 7 compatibility
+== Bitbucket Server 7 compatibility
 
-_BitBucket Server 7.x_ is supported but does no longer support lightweight checkout for pull requests when merge strategy is used for build.
+_Bitbucket Server 7.x_ is supported but does no longer support lightweight checkout for pull requests when merge strategy is used for build.
 
 IMPORTANT: In order to have the pull request process working the "Call Changes api" option must be
 enabled in _Manage Jenkins_ » _Configure System_
@@ -83,12 +84,12 @@ image::images/screenshot-9.png[scaledwidth=90%]
 == Webhooks registering
 
 The use of https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html[Bitbucket webhooks]
-allows to trigger builds on branches and pull requests just when a new commit is done. Bitbucket plugin expose a special
+allows to trigger builds on branches and pull requests just when a new commit is done. Bitbucket plugin exposes a special
 service to listen to this webhook requests and acts accordingly by triggering a new reindex and finally
 triggering builds on matching branches or pull requests.
 
 For both _Bitbucket Multibranch_ projects and _Bitbucket Team_ projects there is an option in the configuration page
-to let Jenkins to automatically register the webhooks in all involved repositories.
+to let Jenkins automatically register the webhooks in all involved repositories.
 
 image::images/screenshot-4.png[scaledwidth=90%]
 
@@ -104,7 +105,7 @@ two credentials to configure:
 . *Scan Credentials*: credentials used to access Bitbucket API in order to discover repositories, branches and pull requests.
 If not set then anonymous access is used, so only public repositories, branches and pull requests are discovered and managed. Note that the
 Webhooks auto-register feature requires scan credentials to be set. Only HTTP or OAuth credentials are accepted in this field.
-. *Checkout Credentials*: credentials used to checkout sources once the repository, branch or pull request is discovered. HTTP, SSH and OAuthcredentials
+. *Checkout Credentials*: credentials used to check out sources once the repository, branch or pull request is discovered. HTTP, SSH and OAuth credentials
 are allowed. If not set then _Scan Credentials_ are used.
 
 image::images/screenshot-3.png[scaledwidth=90%]

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

@@ -54,7 +54,7 @@
 /**
  * This class encapsulates all Bitbucket notifications logic.
  * {@link JobCompletedListener} sends a notification to Bitbucket after a build finishes.
- * Only builds derived from a job that was created as part of a multi branch project will be processed by this listener.
+ * Only builds derived from a job that was created as part of a multi-branch project will be processed by this listener.
  */
 public class BitbucketBuildStatusNotifications {
 

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

@@ -141,7 +141,7 @@ public BitbucketGitSCMBuilder withCloneLinks(List<BitbucketHref> cloneLinks) {
 
     /**
      * Returns the {@link BitbucketSCMSource} that this request is against (primarily to allow resolving credentials
-     * against {@link SCMSource#getOwner()}.
+     * against {@link SCMSource#getOwner()}).
      *
      * @return the {@link BitbucketSCMSource} that this request is against
      */
@@ -168,7 +168,7 @@ public List<BitbucketHref> cloneLinks() {
      *                      the {@link #remote()} or {@code null} to let the git client choose between providing its own
      *                      credentials or connecting anonymously.
      * @param protocol the {@link BitbucketRepositoryProtocol} of the {@link Credentials} to use or {@code null}
-     *                 to detect the the protocol based on the credentialsId. Defaults to HTTP if credentials are
+     *                 to detect the protocol based on the credentialsId. Defaults to HTTP if credentials are
      *                 {@code null}.  Enables support for blank SSH credentials.
      * @return {@code this} for method chaining.
      */

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

@@ -222,7 +222,7 @@ public void setCredentialsId(@CheckForNull String credentialsId) {
 
     /**
      * Sets the behavioural traits that are applied to this navigator and any {@link BitbucketSCMSource} instances it
-     * discovers. The new traits will take affect on the next navigation through any of the
+     * discovers. The new traits will take effect on the next navigation through any of the
      * {@link #visitSources(SCMSourceObserver)} overloads or {@link #visitSource(String, SCMSourceObserver)}.
      *
      * @param traits the new behavioural traits.
@@ -241,7 +241,7 @@ public void setTraits(@CheckForNull SCMTrait[] traits) {
 
     /**
      * Sets the behavioural traits that are applied to this navigator and any {@link BitbucketSCMSource} instances it
-     * discovers. The new traits will take affect on the next navigation through any of the
+     * discovers. The new traits will take effect on the next navigation through any of the
      * {@link #visitSources(SCMSourceObserver)} overloads or {@link #visitSource(String, SCMSourceObserver)}.
      *
      * @param traits the new behavioural traits.
@@ -358,7 +358,7 @@ public void setBitbucketServerUrl(String url) {
             setServerUrl(url);
             return;
         }
-        LOGGER.log(Level.WARNING, "Call to legacy setBitbucketServerUrl({0}) method is configuring an url missing "
+        LOGGER.log(Level.WARNING, "Call to legacy setBitbucketServerUrl({0}) method is configuring a url missing "
                 + "from the global configuration.", url);
         setServerUrl(url);
     }

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

@@ -199,7 +199,7 @@ public class BitbucketSCMSource extends SCMSource {
 
     /**
      * Bitbucket Server URL.
-     * An specific HTTP client is used if this field is not null.
+     * A specific HTTP client is used if this field is not null.
      * This value (or serverUrl if this is null) is used in particular
      * to find the current endpoint configuration for this server.
      */
@@ -358,7 +358,7 @@ public void setBitbucketServerUrl(String url) {
             setServerUrl(endpoint.getServerUrl());
             return;
         }
-        LOGGER.log(Level.WARNING, "Call to legacy setBitbucketServerUrl({0}) method is configuring an url missing "
+        LOGGER.log(Level.WARNING, "Call to legacy setBitbucketServerUrl({0}) method is configuring a url missing "
                 + "from the global configuration.", url);
         setServerUrl(url);
     }
@@ -542,7 +542,7 @@ protected void retrieve(@CheckForNull SCMSourceCriteria criteria, @NonNull SCMHe
                 listener.getLogger().format("Connecting to %s using %s%n", getServerUrl(),
                         CredentialsNameProvider.name(scanCredentials));
             }
-            // this has the side-effect of ensuring that repository type is always populated.
+            // this has the side effect of ensuring that repository type is always populated.
             listener.getLogger().format("Repository type: %s%n", WordUtils.capitalizeFully(getRepositoryType().name()));
 
             // populate the request with its data sources

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

@@ -31,7 +31,7 @@
 import jenkins.scm.api.mixin.TagSCMHead;
 
 /**
- * {@link SCMHead} for a BitBucket tags.
+ * {@link SCMHead} for a Bitbucket tags.
  *
  * @since 2.2.11
  */
@@ -84,6 +84,6 @@ public BitbucketRepositoryType getRepositoryType() {
      */
     @Override
     public String getPronoun() {
-        return Messages.BitBucketTagSCMHead_Pronoun();
+        return Messages.BitbucketTagSCMHead_Pronoun();
     }
 }

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

@@ -30,7 +30,7 @@
 import org.kohsuke.accmod.restrictions.DoNotUse;
 
 /**
- * {@link SCMHead} for a BitBucket branch.
+ * {@link SCMHead} for a Bitbucket branch.
  *
  * @since 2.0.0
  */

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

@@ -41,7 +41,7 @@
 import org.kohsuke.accmod.restrictions.NoExternalUse;
 
 /**
- * {@link SCMHead} for a BitBucket Pull request
+ * {@link SCMHead} for a Bitbucket pull request
  *
  * @since 2.0.0
  */
@@ -261,7 +261,7 @@ public SCMRevision migrate(@NonNull BitbucketSCMSource source,
                                    @NonNull AbstractGitSCMSource.SCMRevisionImpl revision) {
             PullRequestSCMHead head = migrate(source, (FixLegacy) revision.getHead());
             return head != null ? new PullRequestSCMRevision<>(head,
-                    // ChangeRequestCheckoutStrategy.HEAD means we ignore the target revision
+                    // ChangeRequestCheckoutStrategy.HEAD means we ignore the target revision,
                     // so we can leave it null as a placeholder
                     new AbstractGitSCMSource.SCMRevisionImpl(head.getTarget(), null),
                     new AbstractGitSCMSource.SCMRevisionImpl(head, revision.getHash()

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

@@ -74,15 +74,15 @@ private Object readResolve() throws ObjectStreamException {
         if (metadata != null) {
             // we just want to flag this as a PR, the legacy data did not contain the required information
             // then the temporary PR class will be resolved by GitMigrationImpl when the
-            // context to look-up the correct target is (hopefully) available. If the context is not available
+            // context to look up the correct target is (hopefully) available. If the context is not available
             // then worst case  we will end up triggering a rebuild on next index / event via take-over
             return new PR(repoOwner, repoName, getName(), metadata.getId(), new BranchSCMHead("\u0000", null));
         }
         return new BranchSCMHead(getName(), null);
     }
 
     /**
-     * Marker class to ensure that we do not attempt apply an {@link SCMHeadMigration} on all
+     * Marker class to ensure that we do not attempt to apply a {@link SCMHeadMigration} on all
      * {@link PullRequestSCMHead} instances, rather we only apply it on ones that need migration. We need to use a
      * {@link ChangeRequestSCMHead} in order to retain the correct categorization of {@link SCMHead} instances
      * in the event that the {@link GitMigrationImpl} fail to resolve the target.
@@ -161,7 +161,7 @@ public SCMRevision migrate(@NonNull BitbucketSCMSource source,
                                    @NonNull AbstractGitSCMSource.SCMRevisionImpl revision) {
             PullRequestSCMHead head = migrate(source, (PR) revision.getHead());
             return head != null ? new PullRequestSCMRevision<>(head,
-                    // ChangeRequestCheckoutStrategy.HEAD means we ignore the target revision
+                    // ChangeRequestCheckoutStrategy.HEAD means we ignore the target revision,
                     // so we can leave it null as a placeholder
                     new AbstractGitSCMSource.SCMRevisionImpl(head.getTarget(), null),
                     new AbstractGitSCMSource.SCMRevisionImpl(head, revision.getHash()

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/BitbucketApi.java

@@ -295,7 +295,7 @@ List<? extends BitbucketRepository> getRepositories(@CheckForNull UserRoleInRepo
      * Returns a list of all children file for the given folder.
      *
      * @param parent to list
-     * @return a iterable of {@link SCMFile} children of the given folder.
+     * @return an iterable of {@link SCMFile} children of the given folder.
      * @throws IOException if there was a network communications error.
      * @throws InterruptedException if interrupted while waiting on remote communications.
      */

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/BitbucketApiFactory.java

@@ -19,7 +19,7 @@ public abstract class BitbucketApiFactory implements ExtensionPoint {
     /**
      * Tests if the supplied URL is supported by this factory.
      *
-     * @param serverUrl the server URL (may be {@code null}, e.g. for BitBucket Cloud)
+     * @param serverUrl the server URL (may be {@code null}, e.g. for Bitbucket Cloud)
      * @return {@code true} if this factory can connect to the specified URL.
      */
     protected abstract boolean isMatch(@Nullable String serverUrl);

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/credentials/BitbucketClientCertificateAuthenticatorSource.java

@@ -60,7 +60,7 @@ public BitbucketClientCertificateAuthenticator convert(@NonNull StandardCertific
      * Whether this source works in the given context. For client certs, only HTTPS BitbucketServer instances make sense
      *
      * @param ctx the context
-     * @return whether or not this can authenticate given the context
+     * @return whether this can authenticate given the context
      */
     @Override
     public boolean isFit(AuthenticationTokenContext ctx) {

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/credentials/BitbucketOAuthAuthenticatorSource.java

@@ -40,7 +40,7 @@ public BitbucketOAuthAuthenticator convert(
      * BitbucketServer instances make sense
      *
      * @param ctx the context
-     * @return whether or not this can authenticate given the context
+     * @return whether this can authenticate given the context
      */
     @Override
     public boolean isFit(AuthenticationTokenContext ctx) {

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/avatars/AvatarCache.java

@@ -115,7 +115,7 @@ public class AvatarCache implements UnprotectedRootAction {
 
     /**
      * The time this service was started (used as the last modified for generated
-     * avatars.
+     * avatars).
      */
     private final long startedTime;
 
@@ -347,7 +347,7 @@ public HttpResponse doDynamic(StaplerRequest req, @QueryParameter String request
         final CacheEntry avatar = getCacheEntry(key, null);
         final long since = req.getDateHeader("If-Modified-Since");
 
-        // If no avatar, all it unmodified
+        // If no avatar, all is unmodified
         if (avatar == null || !avatar.canFetch()) {
             if (startedTime <= since) {
                 return new HttpResponse() {

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/client/BitbucketCloudApiClient.java

@@ -321,7 +321,7 @@ private boolean shouldIgnore(BitbucketPullRequest pr) {
     }
 
     /**
-     * Make available commit informations in a lazy way.
+     * Make available commit information in a lazy way.
      *
      * @author Nikolas Falco
      */

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/client/pullrequest/BitbucketPullRequestValue.java

@@ -86,7 +86,7 @@ public String getAuthorLogin() {
 
     @Override
     public String getAuthorEmail() {
-        // return null because BitBucket Cloud hides users emails
+        // return null because Bitbucket Cloud hides users emails
         return null;
     }
 

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/endpoints/AbstractBitbucketEndpoint.java

@@ -98,7 +98,7 @@ public abstract class AbstractBitbucketEndpoint extends AbstractDescribableImpl<
     /**
      * A Jenkins Server Root URL should end with a slash to use with webhooks.
      *
-     * @param rootUrl the original value of an URL which would be normalized
+     * @param rootUrl the original value of a URL which would be normalized
      * @return the normalized URL ending with a slash
      */
     @NonNull

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/filesystem/BitbucketSCMFileSystem.java

@@ -191,7 +191,7 @@ public SCMFileSystem build(@NonNull SCMSource source, @NonNull SCMHead head, @Ch
                     if (endpoint != null && endpoint.getServerVersion() != BitbucketServerVersion.VERSION_7) {
                         ref = "pull-requests/" + pr.getId() + "/merge";
                     } else {
-                        // returning null to fallback to heavyweight checkout
+                        // returning null to fall back to heavyweight checkout
                         return null;
                     }
                 }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/hooks/WebhookAutoRegisterListener.java

@@ -260,7 +260,7 @@ private List<BitbucketSCMSource> getBitbucketSCMSources(SCMSourceOwner owner) {
 
     /**
      * We need a single thread executor to run webhooks operations in background but in order.
-     * Registrations and removals need to be done in the same order than they were called by the item listener.
+     * Registrations and removals need to be done in the same order as they were called by the item listener.
      */
     private static synchronized ExecutorService getExecutorService() {
         if (executorService == null) {

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/hooks/WebhookConfiguration.java

@@ -214,7 +214,7 @@ private static List<String> getNativeServerEvents(String serverUrl) {
             case VERSION_5_10:
                 return NATIVE_SERVER_EVENTS_v6;
             case VERSION_6:
-                // plugin version 2.9.1 introduced VERSION_6 setting for BitBucket but it
+                // plugin version 2.9.1 introduced VERSION_6 setting for Bitbucket but it
                 // actually applies
                 // to Version 5.10+. In order to preserve backwards compatibility, rather than
                 // remove