chore: add migration guide for v5

README.md

@@ -4,6 +4,11 @@
 [![NuGet](https://img.shields.io/nuget/v/Unleash.Client.svg)](https://www.nuget.org/packages/Unleash.Client/)
 
 
+>  **Migrating to v5**
+>
+> If you use [bootstrapping](#bootstrapping), [custom strategies](#custom-strategies), or a custom JSON serializer, read the complete [migration guide](./v5_MIGRATION_GUIDE.md) before upgrading to v5.
+
+
 ## Introduction
 
 Unleash Client SDK for .Net. It is compatible with the

v5_MIGRATION_GUIDE.md

@@ -0,0 +1,46 @@
+# Migrating to Unleash-Client-Dotnet 5.0.0
+
+This guide highlights the key changes you should be aware of when upgrading to v5.0.0 of the Unleash client.
+
+## Custom strategy changes
+
+Custom strategies no longer provide the option to access the constraints in their interface. The method `bool IsEnabled(Dictionary<string, string> parameters, UnleashContext context, IEnumerable<Constraint> constraints)` no longer exists. Other than that, custom strategies remain unchanged.
+
+## Direct access to feature toggles
+
+Direct access to the feature toggle objects through `UnleashClient.FeatureToggles` has been removed. All classes related to the internal representation of feature toggles are no longer publicly accessible in the SDK.
+
+The SDK now provides a `UnleashClient.ListKnownToggles` method, which returns a list of feature toggle names, their type, and the project they're bound to.
+
+The client also no longer provides access to listing the variants bound to a feature flag through `UnleashClient.GetVariants`. We determined that this was exposing internal abstractions that should remain within the SDK. However, if you have a strong use case for this, please open an issue.
+
+## Bootstrapping changes
+
+Due to the changes in the previous section, bootstrapping classes are now required to return a `String` instead of a `FeatureToggleCollection`. The string should be a JSON string representing the response returned from your Unleash instance's `api/client/features` endpoint. In practice, that means if you previously had a `Read` method in your bootstrapping class like so:
+
+``` dotnet
+
+public ToggleCollection Read()
+{
+    var json = settings.FileSystem.ReadAllText(filePath);
+    return settings.JsonSerializer.Deserialize<ToggleCollection>(json);
+}
+
+```
+
+You can simplify it to:
+
+``` dotnet
+
+public string Read()
+{
+    return settings.FileSystem.ReadAllText(filePath);
+}
+
+```
+
+## Custom serializers
+
+In v4.x and before, the SDK provided the option of mounting a custom JSON serializer. This option has been removed in v5.x; the SDK now relies on `System.Text.Json` with no option to override it. If you previously provided a custom serializer to access `System.Text.Json`, it's now safe to remove it.
+
+If you use NewtonSoft you don't have to make any changes.