Release procedure for branches and some javadoc (#627)

Ensured it is possible to release from release branches.

* Increased number of commits to prepare release notes for
* Ensured mockito is not published to bintray when using release dryRun
* After 2.1.0 is out I will overhaul the release logic and make it perfect :D Currently it is hard to test and work with
* Updated the message emitted from the build, otherwise I was confused with bintrayUpload task behavior.
* Manually bumped version.properties
* Updated the javadoc

Fixes #594

doc/release-notes/official.md

@@ -1,3 +1,26 @@
+### 2.1.0-beta.125 (2016-09-08 03:42 UTC)
+
+* Authors: 4
+* Commits: 24
+  * 15: Szczepan Faber
+  * 5: Continuous Delivery Drone
+  * 3: Brice Dutheil
+  * 1: Divyansh Gupta
+* Improvements: 3
+  * Documentation: 1
+    * Update documentation links in travis config comments [(#558)](https://github.com/mockito/mockito/pull/558)
+  * Remaining changes: 2
+    * Ensured javadocs are correct [(#626)](https://github.com/mockito/mockito/pull/626)
+    * Tweak javadoc [(#625)](https://github.com/mockito/mockito/issues/625)
+
+### 2.1.0-beta.124 (2016-09-07 04:36 UTC)
+
+* Authors: 2
+* Commits: 12
+  * 11: Szczepan Faber
+  * 1: Continuous Delivery Drone
+* No notable improvements. See the commits for detailed changes.
+
 ### 2.1.0-beta.123 (2016-09-06 15:01 UTC)
 
 * Authors: 4

gradle/release.gradle

@@ -83,8 +83,8 @@ task("releaseNeeded") {
         def skippedByCommitMessage = commitMessage?.contains(skipReleaseCommitMessage)
         def customVersion = (commitMessage =~ customReleaseVersionPattern)
         ext.needed = dryRun || customVersion.matches() || (pr == 'false' && isReleasableBranch(branch) && !comparePublications.publicationsEqual && skipEnvVariable != 'true' && !skippedByCommitMessage)
-        logger.lifecycle("Release needed: {}, branch: {}, pull request: {}, dry run: {}, publications equal: {}, skip env variable: {}, skipped by message: {}, customVersion: {}.",
-                needed, branch, pr, dryRun, comparePublications.publicationsEqual, skipEnvVariable, skippedByCommitMessage, customVersion.matches())
+        logger.lifecycle("Release needed: {}, releasable branch: {}, pull request: {}, dry run: {}, publications equal: {}, skip env variable: {}, skipped by message: {}, customVersion: {}.",
+                needed, isReleasableBranch(branch), pr, dryRun, comparePublications.publicationsEqual, skipEnvVariable, skippedByCommitMessage, customVersion.matches())
     }
 }
 
@@ -94,7 +94,7 @@ bintrayUpload {
     doFirst {
         logger.lifecycle troubleshootingInfo
         if (dryRun) {
-            logger.lifecycle "Dry-running the release"
+            logger.lifecycle "Dry-running the release! Although 'bintrayUpload' is executed, it won't upload any binaries ('bintrayUpload.dryRun' property is set)."
         }
     }
 }
@@ -118,7 +118,8 @@ releaseSteps {
 
     step("ensure good chunk of recent commits is pulled for release notes automation") {
         //Travis default clone is pretty shallow
-        run "git", "pull", "--depth", "500"
+        //Loading extra 1K commits (1.x -> 2.x had ~700 commits)
+        run "git", "pull", "--depth", "1000"
     }
 
     def gitAuthor
@@ -128,15 +129,16 @@ releaseSteps {
     step("commit updated javadoc into gh-pages branch") { commitUpdatedJavadoc(buildInfo) }
 
     /*
-            Now we'll start operating on master. This introduces a problem - someone might have pushed changes *after* release process has started
+            Now we'll start operating on branch that we want to release.
+            This introduces a problem - someone might have pushed changes *after* release process has started
             What can happen:
              - bintrayUpload will fail saying that the version is already released
              - git push fails saying that the pull is needed
             Resolutions:
              - see 'TROUBLESHOOTING' section at the top of this file
     */
 
-    step("start operating on master") { run "git", "checkout", "master" }
+    step("start operating on $System.env.TRAVIS_BRANCH") { run "git", "checkout",  System.env.TRAVIS_BRANCH }
 
     step("update release notes") { project.notes.updateReleaseNotes() }
 
@@ -146,11 +148,11 @@ releaseSteps {
     step("create new version tag") { createTag(buildInfo, "v${currentVersion}".toString()) }
             .rollback { run "git", "tag", "-d", "v${currentVersion}".toString()}
 
-    step("commit incremented version on master") { commitIncrementedVersion(currentVersion, buildInfo, project.versionFile) }
+    step("commit incremented version on $System.env.TRAVIS_BRANCH") { commitIncrementedVersion(currentVersion, buildInfo, project.versionFile) }
             .rollback { run "git", "reset", "--hard", "HEAD^" }
 
     step("push changes to all involved branches") {
-        def pushCommandLine = ["git", "push", pushTarget, "master", "gh-pages", "v$currentVersion", "-q"]
+        def pushCommandLine = ["git", "push", pushTarget, System.env.TRAVIS_BRANCH, "gh-pages", "v$currentVersion", "-q"]
         if (dryRun) {
             pushCommandLine << '--dry-run'
         }

src/main/java/org/mockito/Mockito.java

@@ -73,14 +73,14 @@
  *
  * <h3 id="0">0. <a class="meaningful_link" href="#verification">Migrating to 2.1.0</a></h3>
  *
- * In order to continue improving Mockito and further improve the unit testing experience, we want you to upgrade to 2.0.
+ * In order to continue improving Mockito and further improve the unit testing experience, we want you to upgrade to 2.1.0!
  * Mockito follows <a href="http://semver.org/">semantic versioning</a>
  * and contains breaking changes only on major version upgrades.
  * In the lifecycle of a library, breaking changes are necessary
  * to roll out a set of brand new features that alter the existing behavior or even change the API.
  * We hope that you enjoy Mockito 2.1.0!
  * <p>
- * List of breaking changes:
+ * List of breaking changes: TODO 596
  * <ul>
  *     <li>Mockito is decoupled from Hamcrest and custom matchers API has changed, see {@link ArgumentMatcher}
  *     for rationale and migration guide.</li>
@@ -1233,7 +1233,7 @@ public class Mockito extends ArgumentMatchers {
      * <code>ReturnsSmartNulls</code> first tries to return ordinary return values (see {@link ReturnsMoreEmptyValues})
      * then it tries to return SmartNull. If the return type is final then plain null is returned.
      * <p>
-     * <code>ReturnsSmartNulls</code> will be probably the default return values strategy in Mockito 2.0.
+     * <code>ReturnsSmartNulls</code> will be probably the default return values strategy in Mockito 3.0.0
      * <p>
      * Example:
      * <pre class="code"><code class="java">

version.properties

@@ -1,2 +1,2 @@
-version=2.1.0-beta.124
+version=2.1.0-beta.126
 mockito.testng.version=1.0