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>

Author: darxriggs

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()