Update migration guide

src/site/markdown/index.md.vm

@@ -5,7 +5,7 @@ A Java client for the _Automatic Certificate Management Environment_ (ACME) prot
 
 ACME is a protocol that a certificate authority (CA) and an applicant can use to automate the process of verification and certificate issuance.
 
-This Java client helps connecting to an ACME server, and performing all necessary steps to manage certificates. It supports the ACME protocol up to [draft 02](https://tools.ietf.org/html/draft-ietf-acme-acme-02).
+This Java client helps connecting to an ACME server, and performing all necessary steps to manage certificates.
 
 It is an independent open source implementation that is not affiliated with or endorsed by _Let's Encrypt_.
 

src/site/markdown/migration.md

@@ -1,11 +1,19 @@
 # Migration Guide
 
+This document will help you migrate your code to the latest _acme4j_ version.
+
+## Migration to Version 0.9
+
+Version 0.9 brought many changes to the internal API. However, this is only relevant if you run your own CA and make own extensions to _acme4j_ (e.g. if you implement a proprietary `Challenge`). If you use _acme4j_ only for retrieving certificates, you should not notice any changes.
+
+There is one exception: `Authorization.findCombinations()` previously returned `null` if it did not find a matching set of combinations. Now it returns an empty list instead, to avoid unnecessary `null` checks in your code. If you use this method, make sure your code correctly handles empty lists.
+
+If you use `Authorization.findChallenge()`, no changes are necessary to your code.
+
+## Migration to Version 0.6
+
 With version 0.6, _acme4j_ underwent a major change to the API.
 
-This document will help you migrate your code to the latest API when coming from a pre-0.6 release. It should be a matter of a few minutes in most cases.
-
-## What's different?
-
 In previous versions, the resource classes like `Registration` or `Authorization` were plain data transport objects, and an `AcmeClient` was used for the actual server communication. Now, the resource classes communicate directly with the server. The result is an API that is more object oriented.
 
 Instead of an `AcmeClient`, you need a `Session` object now. The `Session` is initialized with the ACME server URI and your account's key pair.
@@ -82,21 +90,3 @@ Note that the `authorize()` method is not needed any more, and has been removed
 As a rule of thumb, you will find the action methods in one of the objects you previously passed as parameter to the `AcmeClient` method. For example, when you wrote `client.triggerChallenge(registration, challenge)`, you will find the new `trigger` method in either `registration` or `challenge` (here it's `challenge`).
 
 The API has also been cleaned up, with many confusing setter methods being removed. If you should miss a setter method, you was actually not supposed to invoke it anyway.
-
-## tl;dr
-
-There is no `AcmeClient` any more, but only a `Session`. The `Session` is bound to the resource classes `Registration`, `Authorization`, `Challenge` and `Certificate`.
-
-All action methods can now be found in one of the resource classes. They are easy to spot because they have a `throws AcmeException` clause.
-
-## Why the change?
-
-In previous versions, _acme4j_ used a client centric approach, with dumb data transport classes that only stored a mix of parameters and return values.
-
-This approach turned out to have major disadvantages. For example, the data transport classes contained setter methods that were supposed to be used only by _acme4j_ itself. Some other setters had to be used by the library user, but only under certain circumstances. To make a long story short: The API was not self-explanatory about when to use what setters.
-
-Also, the old API was too limited to reflect some features of the ACME specifications. `AcmeClient` would have become a bottleneck.
-
-As _acme4j_ is still in beta state, I prefered to make a hard cut and do a major API makeover. Trying to maintain backward compatibility by all means would end up with an overly complicated library.
-
-It took me a lot of time to refactor _acme4j_ and unclutter the API. I hope you like the change.

src/site/markdown/usage/authorization.md

@@ -19,9 +19,9 @@ Collection<Challenge> combination = auth.findCombination(
         Http01Challenge.TYPE, Dns01Challenge.TYPE);
 ```
 
-The returned `combination` contains a single combination of challenges you would have to perform. If the combination consists of more than one challenge, you will have to perform _all of them_ in order to successfully authorize your domain. If `null` is returned, it means that none of your offered challenge types are acceptable to the CA.
+The returned `combination` contains a single combination of challenges you would have to perform. If the combination consists of more than one challenge, you will have to perform _all of them_ in order to successfully authorize your domain. If the returned collection is empty, it means that none of your offered challenge types are acceptable to the CA.
 
-If your software only implements a single challenge type, `findChallenge()` may be a little easier to use:
+If your software only supports a single challenge type, `findChallenge()` may be a little easier to use:
 
 ```java
 Http01Challenge challenge = auth.findChallenge(Http01Challenge.TYPE);