Allow BWC Testing against a specific branch

TESTING.asciidoc

@@ -471,6 +471,29 @@ is tested depends on the branch. On master, this will test against the current
 stable branch. On the stable branch, it will test against the latest release
 branch. Finally, on a release branch, it will test against the most recent release.
 
+=== BWC Testing against a specific branch
+
+Sometimes a backward compatibility change spans two versions. A common case is a new functionality
+that needs a BWC bridge in and an unreleased versioned of a release branch (for example, 5.x).
+To test the changes, you can instruct gradle to build the BWC version from a local branch instead of
+pulling the release branch from GitHub. You do so using the `tests.bwc.refspec` system property:
+
+-------------------------------------------------
+gradle check -Dtests.bwc.refspec=origin/index_req_bwc_5.x
+-------------------------------------------------
+
+The branch needs to be available on the local clone that the BWC makes of the repository you run the
+tests from. Using the `origin` remote is a handy trick to make sure that a branch is available
+and is up to date in the case of multiple runs.
+
+Example:
+
+Say you need to make a change to `master` and have a BWC layer in `5.x`. You will need to:
+. Create a branch called `index_req_change` off `master`. This will contain your change.
+. Create a branch called `index_req_bwc_5.x` off `5.x`. This will contain your bwc layer.
+. If not running the tests locally, push both branches to your remote repository.
+. Run the tests with `gradle check -Dtests.bwc.refspec=origin/index_req_bwc_5.x`
+
 == Coverage analysis
 
 Tests can be run instrumented with jacoco to produce a coverage report in

distribution/bwc/build.gradle

@@ -101,14 +101,15 @@ if (enabled) {
     onlyIf { project.gradle.startParameter.isOffline() == false }
     dependsOn addUpstream
     workingDir = checkoutDir
-    commandLine = ['git', 'fetch', 'upstream']
+    commandLine = ['git', 'fetch']
   }
 
   // this is an Exec task so that the SHA that is checked out is logged
   task checkoutBwcBranch(type: Exec) {
+    def String refspec = System.getProperty("tests.bwc.refspec", "upstream/${bwcBranch}")
     dependsOn fetchLatest
     workingDir = checkoutDir
-    commandLine = ['git', 'checkout', "upstream/${bwcBranch}"]
+    commandLine = ['git', 'checkout', refspec]
   }
 
   File bwcDeb = file("${checkoutDir}/distribution/deb/build/distributions/elasticsearch-${bwcVersion}.deb")