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 use 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,42 @@
+# 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 will return a list of feature toggle names, their type and the project they're bound to.
+
+## 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);
+}
+
+```
+
+This can now be simplified to:
+
+``` dotnet
+
+public string Read()
+{
+    return settings.FileSystem.ReadAllText(filePath);
+}
+
+```
+
+## Custom serializers
+
+In v4.x and before, the SDK provided the option to use NewtonSoft or mount a custom JSON serializer. This option has been removed in v5.x, the SDK now relies on System.Text.Json and no option to override that is provided. If you were previously providing a custom serializer to access System.Text.Json, that's now safe to remove. Users who were previously relying on NewtonSoft shouldn't have to make any changes.