Docs: Add migration guide from 1.x to 2.x

README.md

@@ -4,6 +4,37 @@
 [![Coverage Status](https://img.shields.io/coverallsCoverage/github/Unleash/unleash-client-php?label=Code%20Coverage)](https://coveralls.io/github/Unleash/unleash-client-php?branch=main)
 [![Download](https://img.shields.io/packagist/dt/unleash/client.svg)](https://packagist.org/packages/unleash/client)
 
+<!-- TOC -->
+  * [Unleash client SDK](#unleash-client-sdk)
+  * [Migrating](#migrating)
+  * [Installation](#installation)
+  * [Usage](#usage)
+    * [Builder](#builder)
+      * [Required parameters](#required-parameters)
+      * [Optional parameters](#optional-parameters)
+  * [Proxy SDK](#proxy-sdk)
+  * [Caching](#caching)
+  * [Bootstrapping](#bootstrapping)
+    * [Custom bootstrap provider](#custom-bootstrap-provider)
+    * [Disabling communication with Unleash server](#disabling-communication-with-unleash-server)
+  * [Strategies](#strategies)
+    * [Default strategy](#default-strategy)
+    * [IP address strategy](#ip-address-strategy)
+    * [User ID strategy](#user-id-strategy)
+    * [Gradual rollout strategy](#gradual-rollout-strategy)
+    * [Hostname strategy](#hostname-strategy)
+    * [Context provider](#context-provider)
+    * [Custom strategies](#custom-strategies)
+  * [Variants](#variants)
+  * [Client registration](#client-registration)
+  * [Metrics](#metrics)
+  * [Custom headers via middleware](#custom-headers-via-middleware)
+  * [Constraints](#constraints)
+  * [GitLab specifics](#gitlab-specifics)
+<!-- TOC -->
+
+## Unleash client SDK
+
 A PHP implementation of the [Unleash protocol](https://www.getunleash.io/)
 aka [Feature Flags](https://docs.gitlab.com/ee/operations/feature_flags.html) in GitLab.
 
@@ -13,6 +44,10 @@ You may also be interested in the [Symfony Bundle](https://github.com/Unleash/un
 > like releasing to only specific users or releasing to a percentage of your user base. Read more in the above linked
 > documentations.
 
+## Migrating
+
+If you're migrating from 1.x to 2.x, you can read the [migration guide](doc/migrating-1.x-2.x.md).
+
 ## Installation
 
 `composer require unleash/client`

doc/migrating-1.x-2.x.md

@@ -0,0 +1,32 @@
+### Migration guide from version 1.x to 2.x
+
+The 2.0 release most of all contains a cleanup of old deprecated functions, classes etc. If you're not using any of
+the deprecated features (except for the deprecated strategies, those are still present in 2.x) and you're not implementing
+any of our interfaces, you should be good to go without a single change!
+
+Basically, you don't need to change anything if all the following is true:
+
+- You were using the builder to create an `Unleash` object
+- You either haven't implemented any of our interfaces, or you implemented even the non-mandatory methods
+- You haven't been using any deperecated features (most notably setting a default context without using custom context provider)
+
+## What's changed:
+
+- Every class that could be made `readonly` was made `readonly` (this shouldn't really mean anything to you, all classes were
+  already `final`, so you couldn't extend them anyway).
+- All interfaces that had methods only typehinted in phpdoc now include proper declarations instead:
+  - `\Unleash\Client\Configuration\Context`
+  - `\Unleash\Client\DTO\Constraint`
+  - `\Unleash\Client\DTO\Feature`
+  - `\Unleash\Client\DTO\Strategy`
+- Some previously not required properties of `UnleashConfiguration` object are now mandatory. If you were creating your
+  `Unleash` instance using the `UnleashBuilder`, nothing changes for you.
+- `symfony/event-dispatcher` is now a mandatory dependency
+  - this includes removing the helper classes that wrapped the event dispatcher logic, like `\Unleash\Helper\EventDispatcher`
+    and the stub Symfony files
+- support for setting a default context has been removed, please use a custom context provider
+  - this includes removing the `SettableUnleashContextProvider` interface
+- `getEventDispatcher()` of `UnleashConfiguration` has its type changed from `\Unleash\Helper\EventDispatcher` to `EventDispatcherInterface`
+- `DefaultProxyFeature` had all its properties changed to private, getters have been added and the class is now `JsonSerializable`
+- `AbstractHttpClientTest` is renamed to `AbstractHttpClientTestCase`
+- the stickiness calculator interface now has a 3rd optional parameter