Repository: mockito/mockito
Issue: Review and update documentation for 2.1.0

- [x] update the migration guide (should be easy, there are not many breaking changes, if we miss out we can update in following RC)
- [x] add information about bytebuddy in the migration guide
- [x] mention noteworthy 2.0.0 features (should be easy, there are not many, plus they are already documented :)
- [x] fix odd TODO #593
- [x] review/update @since tags so that they say 2.1.0

Final steps I plan doing (by the EOD Wednesday, tomorrow), in order:
- [x] Test release from release/test (in progress, see Travis CI)
- [x] Merge/cherry-pick changes from "release/test" to master
- [x] Move announcement / motivation text (https://github.com/mockito/mockito/blob/rc-release-notes-demo/doc/release-notes/official.md) to top of "What's new in Mockito 2"
- [x] Final pass over "What's new in Mockito 2", make the information exciting and compelling, emphasize use cases, add missing links
- [x] Update the 2.1.0 information in main Mockito class to link to "What's new in Mockito 2". See "TODO 596" in code
- [x] Review Continuous Delivery [wiki page](https://github.com/mockito/mockito/wiki/Mockito-Continuous-Delivery)
- [x] Update the announcement text (https://github.com/mockito/mockito/blob/rc-release-notes-demo/doc/release-notes/official.md) so that instead of tons of text it just links to "What's new in Mockito 2"
- [x] Review release checklist (mostly done) - #620
- [x] Optional - Add some info in the 'What's new in Mockito 2' about the next steps for engs (e.g. ask to use the new version and give feedback).


Issue comments:
There were separate issues for these points. For example the last point was already fixed by @brice3 in a recent PR

This list nicely summarizes the incompatible changes: https://github.com/mockito/mockito/issues?utf8=✓&q=label%3A%221.*%20incompatible%22%20

@bric3 has started the migration guide: https://github.com/mockito/mockito/wiki/What's-new-in-mockito-2

Migration guide has been updated and I did a small spell check. That LGTM.

Thanks @TimvdLippe
@raphw @szpak @marcingrzejszczak @szczepiq if you want to add other stuff to this migration guide ?

Sorry, I won't find time for anything before JavaZone next week is over. Afterwards, I will have a look!

Given long weekend coming, I can commit to finalize my review / amendments by the end of Wed next week (9/7). Apologies it is not as fast as the crew would like!

Keep in mind that you don't need me to pull the trigger!!!

Guys, we're so close now! It's exciting :)))))

@raphw No problem. Enjoy JavaZone. Also do some advertisement for mockito 2 ;)

I've checked out the migration guide and I found it really good. I was missing an example of a default method but I think @TimvdLippe added that.

I haven't done much (to say the least) with regards to this release so I don't have much to write from myself. Like I told @szczepiq and @bric3 I'm overwhelmed with other projects but I'll try to be more active in the upcoming months (don't promise anything though :/ ).

Definitely I can take over testing questions and support if there are some! :)

I just remembered this, have to add tomorrow: lazy verification.

Lazy verification mention added: https://github.com/mockito/mockito/wiki/What's-new-in-Mockito-2/_compare/e0b49e128f97d703e616c01f0a4893da5295098e...10ba7530dff7a72ef869a16872aca8514c7c8c0a

Cool. This morning I tidied up a bit the wiki, mostly these two : added side page, improved a lot the home page.

Really like these changes, looks a lot nicer!

Op wo 31 aug. 2016 om 14:30 schreef Brice Dutheil <notifications@github.com

> :
> 
> Cool. This morning I tidied up a bit the wiki, mostly these two : added
> side page, improved a lot the home page.
> 
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> https://github.com/mockito/mockito/issues/596#issuecomment-243748893,
> or mute the thread
> https://github.com/notifications/unsubscribe-auth/AFrDb1nMLsk4jJe-dlo4-Z7zGUXM9e_Zks5qlXPagaJpZM4JsMzb
> .

Guys, the "What's new in Mockito 2" is fantastic!!! Thanks a lot!

I like the "What's new in Mockito 2". I'm reviewing Mockito main javadoc. I might have some edits to the "What's new" wiki, will see :)

Yep sure ;)

@szczepiq I think we can close this issue since you reviewed Mockito class :P

I have some edits, hold on :) I'll finish by tomorrow!

Ok we ll monitor the check boxes ;)

@szczepiq Be sure to check out this wiki page as well. https://github.com/mockito/mockito/wiki/Mockito-Continuous-Delivery

And fix or correct issues, I think this could be a starting point if you want to extract the _CDD_

> Move announcement / motivation text (https://github.com/mockito/mockito/blob/rc-release-notes-demo/doc/release-notes/official.md) to top of "What's new in Mockito 2"

I would rather not do this since it clutters the content. That wikipage should be only about "What's new in Mockito 2", not what is upcoming in Mockito 3.

> Final pass over "What's new in Mockito 2", make the information exciting and compelling, emphasize use cases, add missing links

Not sure what you mean with "exciting and compelling" but I would rather not change the current text of the features. Let's keep it formal and clear.

@TimvdLippe migration guide does not mention two BDD enhancements I've developed: #212 and #311. I think it's worth sharing it with the world :)

@mkordas Yes definitely, I have added them!

@TimvdLippe thank you!

> I would rather not do this since it clutters the content. That wikipage should be only about "What's new in Mockito 2", not what is upcoming in Mockito 3.

Good feedback. I'll think how to do it best.

> Not sure what you mean with "exciting and compelling" but I would rather not change the current text of the features. Let's keep it formal and clear.

By compelling I mean ensuring that every feature describes the 'why' well enough (e.g., "why should I care about the feature"). Perhaps this requirement is already met. If that's the case, I don't need to make changes :)

Ah I didn't finish all I wanted :(. I'm pretty happy though. If someone else want's to pick up the work, go for it and pull the trigger :) Otherwise I can pick up the work tomorrow.

@TimvdLippe, I considered your feedback about the 'what's new' page. Eventually, I went ahead and added introduction section. I hope it's ok ;) I added table of contents for people to quickly jump to improvements or incompatibilities. I didn't change much of the original text after all. It's well written. @bric3 , @TimvdLippe GREAT WORK!!!! You contributed not only great code but also great docs. Too many times I see that docs are not emphasized enough in software projects. Docs are part of the product and must be as high quality as code. Thanks for honoring this principle in Mockito.

Damn, I'm proud of this release and you guys!!!!!!!!!! :)))))))))))))))))))))))))))))))))

The introduction looks good! Glad the wording of the changes remained
fairly the same :)

On Thu, 8 Sep 2016, 06:55 Szczepan Faber, notifications@github.com wrote:

> Ah I didn't finish all I wanted :(. I'm pretty happy though. If someone
> else want's to pick up the work, go for it and pull the trigger :)
> Otherwise I can pick up the work tomorrow.
> 
> @TimvdLippe https://github.com/TimvdLippe, I considered your feedback
> about the 'what's new' page. Eventually, I went ahead and added
> introduction section. I hope it's ok ;) I added table of contents for
> people to quickly jump to improvements or incompatibilities. I didn't
> change much of the original text after all. It's well written. @bric3
> https://github.com/bric3 , @TimvdLippe https://github.com/TimvdLippe
> GREAT WORK!!!! You contributed not only great code but also great docs. Too
> many times I see that docs are not emphasized enough in software projects.
> Docs are part of the product and must be as high quality as code. Thanks
> for honoring this principle in Mockito.
> 
> Damn, I'm proud of this release and you guys!!!!!!!!!!
> :)))))))))))))))))))))))))))))))))
> 
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> https://github.com/mockito/mockito/issues/596#issuecomment-245493487,
> or mute the thread
> https://github.com/notifications/unsubscribe-auth/AFrDb9MBUfxlvQ7_h2rI6y6cpZQ8a237ks5qn5UlgaJpZM4JsMzb
> .

Made more progress. I didn't finish on time. My new ETA is weekend :) However, you don't need me to do the release :)

I'l just wait for #628 to be merged then I'll make this branch `release/2.x`

Woah, I'm done!

T_H_A_N_K_S for patience and for pushing me & all of us to make progress on the release.


Pull request review comments:
The href is incorrect and duplicated with [line 84](https://github.com/mockito/mockito/pull/628/files#diff-ddbc0d47e06a589778a6efe24c5d71d3R84)

well spotted. Thanks!


Patch that resolved the issue:
diff --git a/src/main/java/org/mockito/Mockito.java b/src/main/java/org/mockito/Mockito.java
index 7baeea8cbe..92ca4cf668 100644
--- a/src/main/java/org/mockito/Mockito.java
+++ b/src/main/java/org/mockito/Mockito.java
@@ -30,7 +30,7 @@
  * <h1>Contents</h1>
  *
  * <b>
- *      <a href="#0">0. Migrating to 2.1.0</a><br/>
+ *      <a href="#0">0. Migrating to Mockito 2</a><br/>
  *      <a href="#1">1. Let's verify some behaviour! </a><br/>
  *      <a href="#2">2. How about some stubbing? </a><br/>
  *      <a href="#3">3. Argument matchers </a><br/>
@@ -68,36 +68,25 @@
  *      <a href="#35">35. (new) Custom verification failure message (Since 2.1.0)</a><br/>
  *      <a href="#36">36. (new) Java 8 Lambda Matcher Support (Since 2.1.0)</a><br/>
  *      <a href="#37">37. (new) Java 8 Custom Answer Support (Since 2.1.0)</a><br/>
- *
  * </b>
  *
- * <h3 id="0">0. <a class="meaningful_link" href="#verification">Migrating to 2.1.0</a></h3>
+ * <h3 id="0">0. <a class="meaningful_link" href="#mockito2">Migrating to Mockito 2</a></h3>
  *
  * 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: TODO 596
- * <ul>
- *     <li>Mockito is decoupled from Hamcrest and custom matchers API has changed, see {@link ArgumentMatcher}
- *     for rationale and migration guide.</li>
- *     <li>Stubbing API has been tweaked to avoid unavoidable compilation warnings that appeared on JDK7+ platform.
- *     This will only affect binary compatibility, compilation compatibility remains unaffected.</li>
- * </ul>
+ * For comprehensive information about the new release including incompatible changes,
+ * see '<a href="https://github.com/mockito/mockito/wiki/What%27s-new-in-Mockito-2">What's new in Mockito 2</a>' wiki page.
+ * We hope that you enjoy Mockito 2!
+ *
+ * <h3 id="1">1. <a class="meaningful_link" href="#verification">Let's verify some behaviour!</a></h3>
  *
- * <p>
  * The following examples mock a List, because most people are familiar with the interface (such as the
  * <code>add()</code>, <code>get()</code>, <code>clear()</code> methods). <br>
  * In reality, please don't mock the List class. Use a real instance instead.
  *
- *
- *
- *
- * <h3 id="1">1. <a class="meaningful_link" href="#verification">Let's verify some behaviour!</a></h3>
- *
  * <pre class="code"><code class="java">
  * //Let's import Mockito statically so that the code looks clearer
  * import static org.mockito.Mockito.*;


Test patch: