README updates and release pipeline

.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Events Release
+
+permissions:
+  contents: read
+  packages: write
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+       version:
+         type: string
+         required: true
+         description: The version to be published
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        dotnet-version: [ '6.0.x', '7.0.x', '8.0.x' ]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Emit .NET 6.0 Framework Version
+      if: matrix.dotnet == '6.0.x'
+      run: echo "DOTNET_FX_VERSION=net6.0" >> $GITHUB_ENV
+
+    - name: Emit .NET 7.0 Framework Version
+      if: matrix.dotnet == '7.0.x'
+      run: echo "DOTNET_FX_VERSION=net7.0" >> $GITHUB_ENV
+
+    - name: Emit .NET 8.0 Framework Version
+      if: matrix.dotnet == '8.0.x'
+      run: echo "DOTNET_FX_VERSION=net8.0" >> $GITHUB_ENV
+
+    - name: Setup .NET ${{ matrix.dotnet-version }} Framework
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: ${{ matrix.dotnet-version }}
+
+    - name: Restore dependencies
+      run: dotnet restore
+
+    - name: Build
+      run: dotnet build --no-restore -c Release
+
+    - name: Test
+      run: dotnet test --no-build --verbosity normal -c Release /p:CollectCoverage=true /p:CoverletOutputFormat=opencover
+
+    # - name: Collect to Codecov
+    #   uses: codecov/codecov-action@v3
+    #   with:
+    #     token: ${{ secrets.DEVEEL_CODECOV_TOKEN }}
+
+  publish:
+    needs: release
+    runs-on: ubuntu-latest
+    steps:
+    - name: Extract the Version
+      run: echo "VERSION=$(echo ${{ github.event.release.tag_name }} | sed -e 's/^v//')" >> $GITHUB_ENV
+      if: github.event.release.tag_name != null
+
+    - name: Set the Version from Input
+      run: echo "VERSION=${{ inputs.version }}" >> $GITHUB_ENV
+      if: github.event.release.tag_name == null
+
+    - name: Pack NuGet
+      run: dotnet pack -p:PackageVersion=${{ env.VERSION }} -c Release -o ./nuget -p:Version=${{ env.VERSION }}
+
+    - name: Push Github Nuget
+      run: dotnet nuget push ./nuget/*.nupkg -s "https://nuget.pkg.github.com/deveel/index.json" --skip-duplicate --api-key ${{secrets.GITHUB_TOKEN}}
+
+    - name: Push to Github.org
+      run: dotnet nuget push ./nuget/**/*.nupkg --skip-duplicate --api-key ${{secrets.NUGET_API_KEY}} --source https://api.nuget.org/v3/index.json

README.md

@@ -2,11 +2,13 @@
 
 This project provides a simple and lightweight framework for publishing events to subscribers, using common channels and topics.
 
-The ambition of this little framework is to implement a set of patterns and practices that can be used to implement a simple and efficient event-driven architecture in a .NET application, using common approaches to create events and publish them.
+The ambition of this little framework is to implement a set of common patterns and practices that can be used to implement a simple and efficient event-driven architecture in a .NET application, using common approaches to create events and publish them.
+
+It is not in the scope of this project to provide a full-featured event storage system, nor a complex pub/sub application: if you need such a system, you should consider using a message broker or a message queue system (such as RabbitMQ, Kafka, or Azure Service Bus) to implement a more complex and scalable event-driven architecture).
 
 ## Motivation
 
-Often when developing applications, it is necessary to implement a mechanism to notify other parts of the system about changes or events that occur in the application.
+Often when developing applications, it is necessary to implement a mechanism to notify other parts of the system about changes or events that occur in the application: several times the implementor ends up rewriting boilerplate code to manage the events and notifications.
 
 At the present time, there are several ways to implement such a mechanism, such as using a message broker, a message queue, or a pub/sub system, but every organization should implement its own way to manage events and notifications.
 
@@ -51,35 +53,85 @@ To enable this capability, you must first register the publisher in the service
 ```csharp
 using Deveel.Events;
 
-var services = new ServiceCollection();
-services.AddEventPublisher();
+var builder = WebApplication.CreateBuilder(args);
+
+// ...
+
+builder.Services.AddEventPublisher();
 ```
 
 Then, you can create an event and publish it to a channel:
 
 ```csharp
 using Deveel.Events;
 
-var publisher = serviceProvider.GetRequiredService<IEventPublisher>();
+public class MyService {
+    private readonly IEventPublisher publisher;
 
-var @event = new CloudEvent("com.example.myevent", new Uri("http://example.com/events/123"), "Hello, World!") {
-	ContentType = "text/plain",
-	DataSchema = new Uri("http://example.com/schema"),
-	Source = new Uri("http://example.com"),
-	Data = "Hello, World!"
-};
+    public MyService(IEventPublisher publisher) {
+        this.publisher = publisher;
+    }
 
-await publisher.PublishAsync(@event);
+    public async Task PublishEventAsync() {
+        var @event = new CloudEvent("com.example.myevent", new Uri("http://example.com/events/123"), "Hello, World!") {
+            ContentType = "text/plain",
+            DataSchema = new Uri("http://example.com/schema"),
+            Source = new Uri("http://example.com"),
+            Data = "Hello, World!"
+        };
+
+        await publisher.PublishEventAsync(@event);
+    }
+}
 ```
 
 Note that the above example will publish the event to all the channels that are registered in the publisher.
 
+### Publishing from Event Data
+
+If you have a class that represents the data of an event, you can use the `EventAttribute` to decorate such a class to describe the metadata of the event containing it.
+
+For example, consider the following class:
+
+```csharp
+using Deveel.Events.Annotations;
+
+[Event("com.example.myevent", "1.0")]
+public class MyEventData {
+    [Required]
+    public string Message { get; set; }
+}
+```
+
+You can then publish an event using the data class:
+
+```csharp
+using Deveel.Events;
+
+public class MyService {
+    private readonly IEventPublisher publisher;
+
+    public MyService(IEventPublisher publisher) {
+        this.publisher = publisher;
+    }
+
+    public async Task PublishEventAsync() {
+        var data = new MyEventData {
+            Message = "Hello, World!"
+        };
+
+        await publisher.PublishAsync(data);
+    }
+}
+```
+
 ## Future Work
 
 The framework is still in its early stages, and there are several areas that need to be improved and extended.
 
 Some of the areas that we plan to work on in the future are:
 
+- Supporting custom event serializers and deserializers
 - Implementing more publishers for different messaging systems (eg. RabbitMQ, Kafka, etc.)
 - Supporting the deserialization of events from channels, to make consistent the published events are consumed
 - Allow the selection of the channel to publish an event among the registered ones (eg. with named channels)