From b4af29d5dfc883fd03bac79409bd2f682e0d703a Mon Sep 17 00:00:00 2001
From: Alexey Raga <alexey.raga@gmail.com>
Date: Mon, 12 Aug 2024 21:21:37 +1000
Subject: [PATCH] Readme

---
 ...trib.KafkaFlow.CryptoShredding.Avro.csproj |  4 ++
 .../Readme.md                                 | 60 +++++++++++++++++++
 .../Contrib.KafkaFlow.Outbox.csproj           |  6 +-
 .../Contrib.KafkaFlow.ProcessManagers.csproj  |  5 ++
 4 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/src/Contrib.KafkaFlow.CryptoShredding.Avro/Contrib.KafkaFlow.CryptoShredding.Avro.csproj b/src/Contrib.KafkaFlow.CryptoShredding.Avro/Contrib.KafkaFlow.CryptoShredding.Avro.csproj
index adeae54..42e52d8 100644
--- a/src/Contrib.KafkaFlow.CryptoShredding.Avro/Contrib.KafkaFlow.CryptoShredding.Avro.csproj
+++ b/src/Contrib.KafkaFlow.CryptoShredding.Avro/Contrib.KafkaFlow.CryptoShredding.Avro.csproj
@@ -16,4 +16,8 @@
     <PackageReference Include="Nullable" Version="1.3.1" PrivateAssets="all"/>
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="Readme.md" Pack="true" PackagePath="\"/>
+  </ItemGroup>
+
 </Project>
diff --git a/src/Contrib.KafkaFlow.CryptoShredding.Avro/Readme.md b/src/Contrib.KafkaFlow.CryptoShredding.Avro/Readme.md
index 4971a52..5e2e728 100644
--- a/src/Contrib.KafkaFlow.CryptoShredding.Avro/Readme.md
+++ b/src/Contrib.KafkaFlow.CryptoShredding.Avro/Readme.md
@@ -33,6 +33,66 @@ sensitiveData = EncryptedString.FromPlain("secret-value");
 To prevent accidental leakage of secrets, `EncryptedString.Plain` cannot be serialized to Avro. An attempt to do so will result in an
 exception.
 
+### Generating Avro types
+
+Here is an example of an Avro schema that uses encrypted secrets:
+
+```avro
+{
+  "type": "record",
+  "name": "EncryptedMessage",
+  "namespace": "TestContract",
+
+  "fields": [
+    { "name": "secret",
+      "type": { "type": "string", "logicalType": "encrypted-string" } }
+  ]
+}
+```
+
+C# types can be generated using the [avrogen](https://www.nuget.org/packages/Apache.Avro.Tools) tool
+or by using `Contrib.KafkaFlow.CryptoShredding.Avro.Analyzers` package.
+
+In both cases, make sure to register `EncryptedString` as a logical type:
+
+```csharp
+LogicalTypeFactory.Instance.Register(new EncryptedStringLogicalType());
+```
+
+### Using avrogen
+
+Install [avrogen](https://www.nuget.org/packages/Apache.Avro.Tools):
+
+```bash
+$ dotnet tool install Apache.Avro.Tools
+```
+
+Then generate C# types:
+
+```bash
+$ dotnet avrogen -s <schema-file> <output-directory>
+```
+
+### Using Avro Analyzers
+
+Reference the package in your `.csproj` file:
+
+```xml
+<PackageReference Include="Contrib.KafkaFlow.CryptoShredding.Avro.Analyzers"
+                  Version="x.x.x"
+                  OutputItemType="Analyzer"
+                  ReferenceOutputAssembly="false" />
+```
+and add `*.avsc` files:
+
+```xml
+<ItemGroup>
+    <AdditionalFiles Include="avro\*.avsc" />
+</ItemGroup>
+```
+
+C# classes will be generated automatically for all schemas in the `avro` directory.
+
 ## Encryption Process
 
 For serialization to occur, the secrets must be encrypted first, converting `EncryptedString.Plain` into `EncryptedString.Encrypted`. The
diff --git a/src/Contrib.KafkaFlow.Outbox/Contrib.KafkaFlow.Outbox.csproj b/src/Contrib.KafkaFlow.Outbox/Contrib.KafkaFlow.Outbox.csproj
index 7d534ea..bcc2db2 100644
--- a/src/Contrib.KafkaFlow.Outbox/Contrib.KafkaFlow.Outbox.csproj
+++ b/src/Contrib.KafkaFlow.Outbox/Contrib.KafkaFlow.Outbox.csproj
@@ -8,7 +8,7 @@
     <LangVersion>latest</LangVersion>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest</AnalysisLevel>
-    <PackageVersion></PackageVersion>
+    <PackageReadmeFile>Readme.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
@@ -23,4 +23,8 @@
     <PackageReference Include="System.Text.Json" Version="8.0.4" />
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="Readme.md" Pack="true" PackagePath="\"/>
+  </ItemGroup>
+
 </Project>
diff --git a/src/Contrib.KafkaFlow.ProcessManagers/Contrib.KafkaFlow.ProcessManagers.csproj b/src/Contrib.KafkaFlow.ProcessManagers/Contrib.KafkaFlow.ProcessManagers.csproj
index 54b7a12..cc7d9b4 100644
--- a/src/Contrib.KafkaFlow.ProcessManagers/Contrib.KafkaFlow.ProcessManagers.csproj
+++ b/src/Contrib.KafkaFlow.ProcessManagers/Contrib.KafkaFlow.ProcessManagers.csproj
@@ -8,6 +8,7 @@
     <LangVersion>latest</LangVersion>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest</AnalysisLevel>
+    <PackageReadmeFile>Readme.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
@@ -20,4 +21,8 @@
     <PackageReference Include="System.Text.Json" Version="8.0.4" />
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="Readme.md" Pack="true" PackagePath="\"/>
+  </ItemGroup>
+
 </Project>