From bd175715c4dbc3b1170cd18a9423d236888a221e Mon Sep 17 00:00:00 2001
From: Todd <todm@sitecore.net>
Date: Fri, 8 Dec 2023 16:21:27 -0600
Subject: [PATCH] Newtonsoft readme

---
 .../Flurl.Http.Newtonsoft.csproj              |  4 +++-
 src/Flurl.Http.Newtonsoft/README.md           | 21 +++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 src/Flurl.Http.Newtonsoft/README.md

diff --git a/src/Flurl.Http.Newtonsoft/Flurl.Http.Newtonsoft.csproj b/src/Flurl.Http.Newtonsoft/Flurl.Http.Newtonsoft.csproj
index 2c2a2f2b..7837533e 100644
--- a/src/Flurl.Http.Newtonsoft/Flurl.Http.Newtonsoft.csproj
+++ b/src/Flurl.Http.Newtonsoft/Flurl.Http.Newtonsoft.csproj
@@ -4,7 +4,7 @@
     <LangVersion>9.0</LangVersion>
     <GeneratePackageOnBuild>True</GeneratePackageOnBuild>
     <PackageId>Flurl.Http.Newtonsoft</PackageId>
-    <Version>0.9.0-pre2</Version>
+    <Version>0.9.0-pre3</Version>
     <Authors>Todd Menier</Authors>
     <Description>A Newtonsoft-based JSON serializer for Flurl.Http 4.0 and above.</Description>
     <PackageProjectUrl>https://flurl.dev</PackageProjectUrl>
@@ -13,6 +13,7 @@
     <RepositoryType>git</RepositoryType>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageTags>flurl http json</PackageTags>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageReleaseNotes>https://github.com/tmenier/Flurl/releases</PackageReleaseNotes>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
@@ -26,6 +27,7 @@
 
   <ItemGroup>
     <None Include="..\..\icon.png" Pack="true" PackagePath="\" />
+    <None Include="README.md" Pack="true" PackagePath="\" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
     <ProjectReference Include="..\Flurl.Http\Flurl.Http.csproj" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="All" />
diff --git a/src/Flurl.Http.Newtonsoft/README.md b/src/Flurl.Http.Newtonsoft/README.md
new file mode 100644
index 00000000..ce4e95ee
--- /dev/null
+++ b/src/Flurl.Http.Newtonsoft/README.md
@@ -0,0 +1,21 @@
+# Flurl.Http.Newtonsoft
+
+[![NuGet version (Flurl.Http.Newtonsoft)](https://img.shields.io/nuget/v/Flurl.Http.Newtonsoft.svg?style=flat-square)](https://www.nuget.org/packages/Flurl.Http.Newtonsoft/)
+
+Flurl.Http 4.0 [removed](https://github.com/tmenier/Flurl/issues/517) the `Newtonsoft.Json` dependency in favor of `System.Text.Json` for its default JSON serializer implementation. This has several advantages, most notably that it dramatically reduces Flurl's footprint, which is especially important to developers using it in mobile apps and browser platforms.
+
+But it's also a breaking change. Upgrading from 3.x may cause some pains, such as:
+
+- Newtonsoft's [serialization attributes](https://www.newtonsoft.com/json/help/html/serializationattributes.htm) no longer have any effect, and need be replaced by their STJ equivalents.
+- Newtonsoft's [configuration settings](https://www.newtonsoft.com/json/help/html/serializationsettings.htm) also no longer have any effect in Flurl.
+- Support for `dynamic`s has also been [removed](https://github.com/tmenier/Flurl/issues/699) in Flurl, specifically due to the lack of support in STJ.
+
+This package aims to solve these problems, making upgrading easier for those who still want or need Newtonsoft-based serialization. Included in this package:
+
+- `NewtonsoftJsonSearializer`, an instance of which can be assigned to a Flurl client or request via `Settings.JsonSerializer`.
+- Shortcuts for enabling the serializer more "globally":
+    - When using the clientless pattern: `FlurlHttp.Clients.UseNewtonsoft()`
+    - When using DI / [named clients](https://github.com/tmenier/Flurl/issues/770): `new FlurlClientCache().UseNewtonsoft()`
+- Non-generic `dynamic`-returning `GetJson`, `GetJsonList`, `ReceiveJson`, and `ReceiveJsonList` extension methods.
+
+Both `NewtonsoftJsonSerializer` and the `UseNewtonsoft` shortcuts take an optional `JsonSerializerSettings` parameter. In fact, the serializer was lifted directly from 3.x, so you can trust that it's battle-tested and highly performant.
\ No newline at end of file