You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by gi...@apache.org on 2024/01/24 11:02:56 UTC
(pulsar-dotpulsar) branch gh-pages created (now 78d9fa3)
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a change to branch gh-pages
in repository https://gitbox.apache.org/repos/asf/pulsar-dotpulsar.git
at 78d9fa3 deploy: 55be1c5731b8aa7e1506bc19307d8c7e282c77c4
This branch includes the following new commits:
new 78d9fa3 deploy: 55be1c5731b8aa7e1506bc19307d8c7e282c77c4
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(pulsar-dotpulsar) 01/01: deploy: 55be1c5731b8aa7e1506bc19307d8c7e282c77c4
Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch gh-pages
in repository https://gitbox.apache.org/repos/asf/pulsar-dotpulsar.git
commit 78d9fa34bbe43f4dbb0974308f4c089496c85d88
Author: blankensteiner <bl...@users.noreply.github.com>
AuthorDate: Wed Jan 24 11:02:52 2024 +0000
deploy: 55be1c5731b8aa7e1506bc19307d8c7e282c77c4
---
.nojekyll | 0
api/.gitignore | 9 +
api/api/.gitignore | 5 +
api/api/index.md | 3 +
api/assets/favicon.ico | Bin 0 -> 15086 bytes
api/assets/pulsar.svg | 12 +
api/docfx.json | 59 +++++
api/index.md | 107 +++++++++
api/toc.yml | 3 +
decisions/0001-target-dotnet-standard-2-0.md | 52 +++++
decisions/0002-support-visual-studio-and-rider.md | 48 ++++
dev/assets/riderAutoCleanOnCommit.gif | Bin 0 -> 73005 bytes
dev/assets/vs2022CleanOnSave.gif | Bin 0 -> 1019622 bytes
dev/assets/vs2022WithReSharper.gif | Bin 0 -> 185145 bytes
dev/coding-style.md | 91 ++++++++
release-process.md | 257 ++++++++++++++++++++++
16 files changed, 646 insertions(+)
diff --git a/.nojekyll b/.nojekyll
new file mode 100644
index 0000000..e69de29
diff --git a/api/.gitignore b/api/.gitignore
new file mode 100644
index 0000000..11740bc
--- /dev/null
+++ b/api/.gitignore
@@ -0,0 +1,9 @@
+###############
+# folder #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+_site
diff --git a/api/api/.gitignore b/api/api/.gitignore
new file mode 100644
index 0000000..e8079a3
--- /dev/null
+++ b/api/api/.gitignore
@@ -0,0 +1,5 @@
+###############
+# temp file #
+###############
+*.yml
+.manifest
diff --git a/api/api/index.md b/api/api/index.md
new file mode 100644
index 0000000..39c888f
--- /dev/null
+++ b/api/api/index.md
@@ -0,0 +1,3 @@
+# API Documentation
+
+This page hosts the API documentation of DotPulsar.
diff --git a/api/assets/favicon.ico b/api/assets/favicon.ico
new file mode 100644
index 0000000..80aa08d
Binary files /dev/null and b/api/assets/favicon.ico differ
diff --git a/api/assets/pulsar.svg b/api/assets/pulsar.svg
new file mode 100644
index 0000000..92e035c
--- /dev/null
+++ b/api/assets/pulsar.svg
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="134px" height="26px" viewBox="0 0 134 26" version="1.1">
+<g id="surface1">
+<path style=" stroke:none;fill-rule:nonzero;fill:rgb(9.411765%,56.078431%,100%);fill-opacity:1;" d="M 36.582031 8.285156 L 27.640625 8.285156 C 25.222656 3.621094 22.667969 0 19.191406 0 C 14.664062 0 12.535156 3.976562 10.476562 7.847656 L 10.296875 8.183594 L 0 8.183594 L 0 10.484375 L 5.996094 10.484375 C 8.113281 10.484375 8.546875 11.203125 8.546875 11.203125 C 6.882812 13.796875 4.886719 16.359375 1.558594 16.359375 L 0 16.359375 L 0 18.773438 L 1.570312 18.773438 C 8.023438 18.773 [...]
+<path style=" stroke:none;fill-rule:nonzero;fill:rgb(27.45098%,30.588235%,33.72549%);fill-opacity:1;" d="M 47.875 8.269531 L 41.644531 8.269531 L 41.644531 10.527344 L 47.738281 10.527344 C 50.257812 10.527344 51.703125 11.679688 51.703125 13.742188 C 51.703125 15.699219 50.105469 16.957031 47.640625 16.957031 L 41.644531 16.957031 L 41.644531 24.804688 L 44.042969 24.804688 L 44.042969 19.191406 L 47.597656 19.191406 C 50.851562 19.191406 54.125 17.484375 54.125 13.628906 C 54.105469 10 [...]
+<path style=" stroke:none;fill-rule:nonzero;fill:rgb(27.45098%,30.588235%,33.72549%);fill-opacity:1;" d="M 67.953125 17.847656 C 67.953125 21.050781 66.359375 22.816406 63.46875 22.816406 C 60.578125 22.816406 58.910156 20.964844 58.910156 17.730469 L 58.910156 8.269531 L 56.511719 8.269531 L 56.511719 17.847656 C 56.511719 22.304688 59.148438 25.085938 63.402344 25.085938 C 67.652344 25.085938 70.335938 22.328125 70.335938 17.707031 L 70.335938 8.269531 L 67.9375 8.269531 Z M 67.953125 [...]
+<path style=" stroke:none;fill-rule:nonzero;fill:rgb(27.45098%,30.588235%,33.72549%);fill-opacity:1;" d="M 76.363281 8.269531 L 73.980469 8.269531 L 73.980469 24.828125 L 85.292969 24.828125 L 85.292969 22.566406 L 76.363281 22.566406 Z M 76.363281 8.269531 "/>
+<path style=" stroke:none;fill-rule:nonzero;fill:rgb(27.45098%,30.588235%,33.72549%);fill-opacity:1;" d="M 93.96875 15.390625 C 90.527344 14.648438 89.898438 13.863281 89.898438 12.53125 C 89.898438 11.195312 91.15625 10.261719 92.957031 10.261719 C 94.570312 10.261719 96.132812 10.855469 97.34375 11.925781 L 97.585938 12.117188 L 99 10.261719 L 98.777344 10.078125 C 97.171875 8.710938 95.121094 7.988281 93.015625 8.050781 C 89.824219 8.050781 87.511719 10.007812 87.511719 12.753906 C 87 [...]
+<path style=" stroke:none;fill-rule:nonzero;fill:rgb(27.45098%,30.588235%,33.72549%);fill-opacity:1;" d="M 108.0625 8.152344 L 100.566406 24.828125 L 103.046875 24.828125 L 104.933594 20.605469 L 113.183594 20.605469 L 115.042969 24.828125 L 117.617188 24.828125 L 110.121094 8.152344 Z M 105.898438 18.414062 L 109.070312 11.292969 L 112.222656 18.414062 Z M 105.898438 18.414062 "/>
+<path style=" stroke:none;fill-rule:nonzero;fill:rgb(27.45098%,30.588235%,33.72549%);fill-opacity:1;" d="M 129.046875 18.195312 C 131.617188 17.59375 133.136719 15.78125 133.136719 13.300781 C 133.164062 12.050781 132.691406 10.84375 131.828125 9.945312 C 130.535156 8.78125 128.839844 8.179688 127.109375 8.261719 L 119.992188 8.261719 L 119.992188 24.828125 L 122.390625 24.828125 L 122.390625 18.617188 L 126.480469 18.617188 L 131.078125 24.820312 L 134.019531 24.820312 Z M 122.367188 16 [...]
+</g>
+</svg>
diff --git a/api/docfx.json b/api/docfx.json
new file mode 100644
index 0000000..5187694
--- /dev/null
+++ b/api/docfx.json
@@ -0,0 +1,59 @@
+{
+ "metadata": [
+ {
+ "src": [
+ {
+ "src": "..",
+ "files": [
+ "src/DotPulsar/bin/**/net7.0/DotPulsar.dll"
+ ]
+ }
+ ],
+ "dest": "api",
+ "includePrivateMembers": false,
+ "disableGitFeatures": false,
+ "disableDefaultFilter": false,
+ "noRestore": false,
+ "namespaceLayout": "flattened",
+ "memberLayout": "samePage",
+ "allowCompilationErrors": false
+ }
+ ],
+ "build": {
+ "content": [
+ {
+ "files": [
+ "api/**.yml",
+ "api/index.md"
+ ]
+ },
+ {
+ "files": [
+ "toc.yml",
+ "index.md"
+ ]
+ }
+ ],
+ "resource": [
+ {
+ "files": [
+ "assets/**"
+ ]
+ }
+ ],
+ "dest": "_site",
+ "globalMetadata": {
+ "_appTitle": "Official DotPulsar Documentation",
+ "_appFooter": "Copyright © 2019-2023 The Apache Software Foundation. All Rights Reserved. Apache, Pulsar, Apache Pulsar, and the Apache feather logo are trademarks or registered trademarks of The Apache Software Foundation.",
+ "_appLogoPath": "assets/pulsar.svg",
+ "_appFaviconPath": "assets/favicon.ico"
+ },
+ "template": [
+ "default",
+ "modern"
+ ],
+ "postProcessors": [],
+ "keepFileLink": false,
+ "disableGitFeatures": false
+ }
+}
diff --git a/api/index.md b/api/index.md
new file mode 100644
index 0000000..ca78b1e
--- /dev/null
+++ b/api/index.md
@@ -0,0 +1,107 @@
+# DotPulsar
+
+The official .NET client library for [Apache Pulsar](https://pulsar.apache.org/).
+
+DotPulsar is written entirely in C# and implements Apache Pulsar's [binary protocol](https://pulsar.apache.org/docs/en/develop-binary-protocol/).
+
+## What's new?
+
+Have a look at the [changelog](https://github.com/apache/pulsar-dotpulsar/blob/master/CHANGELOG.md).
+
+## Getting Started
+
+Let's take a look at a "Hello world" example, where we first produce a message and then consume it. Note that the topic and subscription will be created if they don't exist.
+
+First, we need a Pulsar setup. See [Pulsar docs](https://pulsar.apache.org/docs/getting-started-home/) for how to set up a local standalone Pulsar instance.
+
+Install the NuGet package [DotPulsar](https://www.nuget.org/packages/DotPulsar/) and run the follow code example:
+
+```csharp
+using DotPulsar;
+using DotPulsar.Extensions;
+
+const string myTopic = "persistent://public/default/mytopic";
+
+// connecting to pulsar://localhost:6650
+await using var client = PulsarClient.Builder().Build();
+
+// produce a message
+await using var producer = client.NewProducer(Schema.String).Topic(myTopic).Create();
+await producer.Send("Hello World");
+
+// consume messages
+await using var consumer = client.NewConsumer(Schema.String)
+ .SubscriptionName("MySubscription")
+ .Topic(myTopic)
+ .InitialPosition(SubscriptionInitialPosition.Earliest)
+ .Create();
+
+await foreach (var message in consumer.Messages())
+{
+ Console.WriteLine($"Received: {message.Value()}");
+ await consumer.Acknowledge(message);
+}
+```
+
+For a more in-depth tour of the API, please visit the [Wiki](https://github.com/apache/pulsar-dotpulsar/wiki).
+
+## Supported features
+
+- Service discovery
+- Automatic reconnect
+- TLS connections
+- Pulsar Proxy
+- Producer - send with custom metadata
+- Producer - send with event time, sequence id, and delayed message delivery
+- Producer - send with key and ordering key
+- Producer - partitioned topics
+- Consumer - subscription with initial position and priority level
+- Consumer - subscription types exclusive, shared, failover, and key shared
+- Consumer - receive and single + cumulative acknowledge
+- Consumer/Reader - seek on message-id and publish time
+- Consumer - unsubscribe
+- Consumer - compacted topics
+- Reader API
+- Read/Consume/Acknowledge batched messages
+- Telemetry
+ - [Tracing](https://github.com/apache/pulsar-dotpulsar/wiki/Tracing)
+ - [Metrics](https://github.com/apache/pulsar-dotpulsar/wiki/Metrics)
+- Authentication
+ - TLS Authentication
+ - JSON Web Token Authentication
+ - Custom Authentication
+- [Message compression](https://github.com/apache/pulsar-dotpulsar/wiki/Compression)
+ - LZ4
+ - ZLIB
+ - ZSTD
+ - SNAPPY
+- Schemas
+ - Boolean
+ - Bytes (using `byte[]` and `ReadOnlySequence<byte>`)
+ - String (UTF-8, UTF-16, and US-ASCII)
+ - INT8, INT16, INT32, and INT64
+ - Float and Double
+ - Time (using TimeSpan)
+ - Timestamp and Date (using DateTime)
+
+For a horizontal comparison with more language-specific clients, see [Client Feature Matrix](https://pulsar.apache.org/client-feature-matrix/).
+
+## Join Our Community
+
+Apache Pulsar has a [Slack instance](https://pulsar.apache.org/contact/), and there you'll find us in the #dev-dotpulsar channel.
+
+## Versioning
+
+We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/apache/pulsar-dotpulsar/tags).
+
+## Contribution
+
+* **Daniel Blankensteiner** - *Initial work* - [Danske Commodities](https://github.com/DanskeCommodities)
+
+Contributions are welcomed and greatly appreciated. See also the list of [contributors](https://github.com/apache/pulsar-dotpulsar/contributors) who participated in this project. Read the [CONTRIBUTING](https://github.com/apache/pulsar-dotpulsar/blob/master/CONTRIBUTING.md) guide for how to participate.
+
+If your contribution adds Pulsar features for C# clients, you need to update both the [Pulsar docs](https://pulsar.apache.org/docs/client-libraries/) and the [Client Feature Matrix](https://pulsar.apache.org/client-feature-matrix/). See [Contribution Guide](https://pulsar.apache.org/contribute/site-intro/#pages) for more details.
+
+## License
+
+This project is licensed under [Apache License, Version 2.0](https://apache.org/licenses/LICENSE-2.0).
diff --git a/api/toc.yml b/api/toc.yml
new file mode 100644
index 0000000..fffb014
--- /dev/null
+++ b/api/toc.yml
@@ -0,0 +1,3 @@
+- name: API
+ href: api/
+ homepage: api/index.md
diff --git a/decisions/0001-target-dotnet-standard-2-0.md b/decisions/0001-target-dotnet-standard-2-0.md
new file mode 100644
index 0000000..88bee86
--- /dev/null
+++ b/decisions/0001-target-dotnet-standard-2-0.md
@@ -0,0 +1,52 @@
+# Target .NET Standard 2.0
+
+## Context and Problem Statement
+
+Targeting multiple frameworks might increase the maintenance cost and therefore require careful consideration.
+The added maintenance cost of a target, if any, must be justifiable considering the expected user base increase that the target brings.
+
+Maintenance costs are typically related to the challenge of only using the lowest common denominator regarding APIs and dependencies or writing target-specific code.
+Usually, the latter is chosen to gain the advantages of e.g. speed and code readability that the new APIs and dependencies offer.
+
+## Decision Drivers
+
+* We want to target as many of the supported .NET versions as possible
+* We want to ensure that the code base is readable, evolvable, and performant
+
+## Considered Options
+
+* Target .NET Standard 2.0
+* Target supported .NET Frameworks
+* Don't target .NET Standard and .NET Framework
+
+## Decision Outcome
+
+Chosen option: "Target .NET Standard 2.0", because we can support a lot of "legacy" software with little effort.
+
+Targeting .NET Framework(s) directly will require developers and the build and deployment pipelines to use Windows-only versions of .NET.
+Therefore .NET Framework should be targeted indirectly by targeting .NET Standard instead.
+The latest (and final) version of .NET Standard is 2.1 and it's not supported by any versions of .NET Framework. However, .NET Standard 2.0 is supported by .NET Framework 4.6.2 and up.
+As of this writing (16th of November 2023), the latest version of .NET Framework is version 4.8.1, which was released on the 9th of August 2022.
+Microsoft has set an end date for support for .NET Framework 4.6.2 on the 12th of January 2027 and there is currently no end date for .NET Framework 4.8.1.
+We can therefore expect .NET Framework to live for many years to come.
+
+## Pros and Cons of the Options
+
+### Target .NET Standard 2.0
+
+* Good, because it is supported by .NET Framework 4.6.2 and up
+* Bad, because some NuGet packages have removed support for it
+* Bad, because some target-specific code must be written to support it
+
+### Target .NET Framework
+
+* Good, because it has a huge user base
+* Good, because a lot of versions are still supported by Microsoft
+* Bad, because it is Windows only
+* Bad, because some NuGet packages have removed support for it
+* Bad, because some target-specific code must be written to support it
+
+### Don't target .NET Standard and .NET Framework
+
+* Good, because the developers can use the latest APIs and dependencies
+* Bad, because we are losing a huge user base
\ No newline at end of file
diff --git a/decisions/0002-support-visual-studio-and-rider.md b/decisions/0002-support-visual-studio-and-rider.md
new file mode 100644
index 0000000..2382a97
--- /dev/null
+++ b/decisions/0002-support-visual-studio-and-rider.md
@@ -0,0 +1,48 @@
+# Support Visual Studio and Rider
+
+## Context and Problem Statement
+
+There are multiple IDEs to choose from when coding C#. The three most popular choices are Visual Studio, Visual Studio Code, and Rider.
+Some IDEs will add certain files and folders and have their own opinion on when something is a warning and how code should be (auto)formatted.
+If multiple IDEs are supported, then it must be ensured that the IDEs agree on warnings and formatting.
+This can be achieved by carefully constructing a .editorconfig and *.DotSettings file that aligns formatting and warning behavior.
+
+## Decision Drivers
+
+* We want developers to be able to use their favorite IDE
+* We want to ensure that different IDEs don't conflict, require unreasonable restructuring, or disagree on code formatting and warnings
+
+## Considered Options
+
+* Support Visual Studio
+* Support Visual Studio Code
+* Support Rider
+
+## Decision Outcome
+
+Chosen options: "Support Visual Studio" and "Support Rider", because the .NET developer base is divided between Visual Studio and Rider and we can support both.
+
+Visual Studio Code is not a full-featured IDE and doesn't work with the code base out of the box.
+It is, currently, deemed to be too much (and unreasonable) work for too small a developer base to consider adding support for Visual Studio Code.
+
+## Validation
+
+Open the solution and run a solution-wide "Analyze and Code Cleanup" in Visual Studio or "Reformat and Cleanup" in Rider.
+Visual Studio and Rider should agree on the end result.
+
+## Pros and Cons of the Options
+
+### Support Visual Studio
+
+* Good, because it has a huge user base
+* Bad, because it is Windows only
+
+### Support Visual Studio Code
+
+* Good, because it is cross-platform
+* Bad, because it doesn't work with the code base out of the box
+
+### Support Rider
+
+* Good, because it has a huge user base and is cross-platform
+* Bad, because it is not free and requires a license
\ No newline at end of file
diff --git a/dev/assets/riderAutoCleanOnCommit.gif b/dev/assets/riderAutoCleanOnCommit.gif
new file mode 100644
index 0000000..c66822f
Binary files /dev/null and b/dev/assets/riderAutoCleanOnCommit.gif differ
diff --git a/dev/assets/vs2022CleanOnSave.gif b/dev/assets/vs2022CleanOnSave.gif
new file mode 100644
index 0000000..6bff283
Binary files /dev/null and b/dev/assets/vs2022CleanOnSave.gif differ
diff --git a/dev/assets/vs2022WithReSharper.gif b/dev/assets/vs2022WithReSharper.gif
new file mode 100644
index 0000000..85f92a2
Binary files /dev/null and b/dev/assets/vs2022WithReSharper.gif differ
diff --git a/dev/coding-style.md b/dev/coding-style.md
new file mode 100644
index 0000000..4c2ddc7
--- /dev/null
+++ b/dev/coding-style.md
@@ -0,0 +1,91 @@
+<a name="readme-top"></a>
+
+<br />
+<div align="center">
+<h3 align="center">C# coding style guide</h3>
+ <p align="center">
+ DotPulsar style guide for C#
+ </p>
+</div>
+
+<!-- TABLE OF CONTENTS -->
+
+<!-- TOC start -->
+- [Why we need a style guide](#why-we-need-a-style-guide)
+- [The Solution](#the-solution)
+ * [Philosophy behind the choices made in the EditorConfig and DotSettings](#philosophy)
+- [Setup auto clean in IDEs](#setup-auto-clean-in-ides)
+ * [Rider](#rider)
+ * [Visual Studio with Resharper](#visual-studio-with-resharper)
+ * [Visual Studio.](#visual-studio)
+<!-- TOC end -->
+
+<!-- TOC --><a name="why-we-need-a-style-guide"></a>
+## Why we need a style guide
+
+<a name="why-we-need-a-style-guide"></a>
+
+* Create a consistent look to the code, so that developers can focus on content.
+* Onboarding new developers become easier because the code is uniform and easier to understand.
+* Reduction of development time by allowing code reviewers to focus on substance.
+
+<!-- TOC --><a name="the-solution"></a>
+## The Solution
+
+Introducing the EditorConfig and DotSettings files!
+
+The [EditorConfig] helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs.
+The EditorConfig is used to define coding styles, and because the file is human-readable it works nicely with version control systems.
+
+DotSettings is a file used to set [Layer-based settings] for Rider and ReSharper.
+This file contains the 'DotPulsar: Full Cleanup' cleanup profile and the setting for enabling auto clean up on save for Visual Studio with ReSharper.
+
+<!-- TOC --><a name="philosophy"></a>
+### Philosophy behind the choices made in the EditorConfig and DotSettings
+
+The editorconfig default settings have been chosen to prioritize style compatibility between Jetbrains and Microsoft offerings.
+Developers should still have the choice of what style overall makes sense for them in a given coding scenario.
+Therefore the configs contain no strict rules on if a method should be an expression body or block body.
+But it will enforce small things, like an empty space at the end of each cs file.
+
+## Setup auto clean in IDEs
+
+<!-- TOC --><a name="rider"></a>
+### Rider
+
+1. In the commit window, click the gear icon.
+2. Make sure only the "Cleanup 'DotPulsar: Full Cleanup' profile" is checked. ("Check TODO" can be left on or off according to your preference)
+
+
+
+<!-- TOC --><a name="visual-studio-with-resharper"></a>
+### Visual Studio with Resharper
+
+1. Goto Extensions, then ReSharper and click Options...
+2. Find Code Editing then Code Cleanup and click General
+3. Check "Automatically run cleanup when saving a file (not supported for shared/linked files)"
+4. Goto Profiles and make sure the profile 'DotPulsar: Full Cleanup' is set as the default
+5. Save
+
+
+
+<!-- TOC --><a name="visual-studio"></a>
+### Visual Studio.
+
+To get Visual Studio to automatically enforce the code style on file save, do the following
+
+1. Goto Tools and then Options...
+2. Text Editor -> Code Cleanup
+3. Check the box "Run Code Cleanup profile on Save"
+4. click ok
+
+
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- MARKDOWN LINKS & IMAGES -->
+
+<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
+
+[EditorConfig]: https://editorconfig.org/
+[Layer-based settings]: https://www.jetbrains.com/help/rider/Sharing_Configuration_Options.html
diff --git a/release-process.md b/release-process.md
new file mode 100644
index 0000000..ee862f0
--- /dev/null
+++ b/release-process.md
@@ -0,0 +1,257 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+This guide illustrates how to perform a release for Apache DotPulsar.
+
+In general, you need to perform the following steps:
+
+1. Version Update & Tagging.
+2. GitHub Prerelease Creation.
+3. Source Code Download.
+4. Artifact Staging & Signing.
+5. Voting Process Execution.
+6. Vote Summary.
+7. Release Artifacts.
+8. GitHub Release Creation.
+9. Release Announcement.
+
+#### Managing backporting of patches
+When we need to create a backporting patch, we simply create a branch for the version that requires the backport.
+We can easily locate a specific version using git tags. We do not create a branch until the actual need arises.
+
+### Requirements
+- [Creating GPG keys to sign release artifacts](https://pulsar.apache.org/contribute/create-gpg-keys/)
+
+## Versioning
+Bump up the version number as follows.
+
+* Major version (e.g. 2.8.0 => 3.0.0)
+ * Changes that break backward compatibility
+* Minor version (e.g. 2.8.0 => 2.9.0)
+ * Backward compatible new features
+* Patch version (e.g. 2.8.0 => 2.8.1)
+ * Backward compatible bug fixes
+
+## Steps in detail
+
+Define the version to be released (adjust to the real version):
+
+```shell
+export DOTPULSAR_VERSION=3.0.0
+export DOTPULSAR_VERSION_RC=3.0.0-rc.1
+```
+
+1. Version Update & Tagging.
+
+Update the information in `CHANGELOG.md` and send a PR with the changes.
+
+Be sure to make the commit message `Make ready for release $DOTPULSAR_VERSION_RC`
+
+2. GitHub Prerelease Creation.
+
+Browse to https://github.com/apache/pulsar-dotpulsar/releases/new
+
+Create a tag `$DOTPULSAR_VERSION_RC`
+
+Create a release title: `DotPulsar $DOTPULSAR_VERSION_RC`
+
+Navigate to the GitHub page for Pulsar at https://github.com/apache/pulsar-dotpulsar/blob/master/CHANGELOG.md. Locate the specific version labeled X.X.X-rc.X in the changelog and transfer all the modifications or updates listed for that version into the designated 'Describe this release' text box.
+
+Make sure the `Set as a pre-release` checkbox is checked!
+
+Publish the release.
+
+3. Source Code Packaging.
+
+Check out the RC tag and package source code into a tarball:
+
+```shell
+git checkout $DOTPULSAR_VERSION_RC
+git archive --format=tar.gz \
+ --output="$(pwd)/pulsar-dotpulsar-$DOTPULSAR_VERSION_RC/pulsar-dotpulsar-$DOTPULSAR_VERSION-src.tar.gz" \
+ --prefix="pulsar-dotpulsar-$DOTPULSAR_VERSION-src"
+```
+
+4. Artifact Staging & Signing.
+
+The src artifact need to be signed and uploaded to the dist SVN repository for staging.
+
+```shell
+gpg -b --armor pulsar-dotpulsar-$DOTPULSAR_VERSION-src.tar.gz
+shasum -a 512 pulsar-dotpulsar-$DOTPULSAR_VERSION-src.tar.gz > pulsar-dotpulsar-$DOTPULSAR_VERSION-src.tar.gz.sha512
+```
+
+Create a candidate directory for uploading artifacts, and then check it out:
+
+```shell
+svn mkdir -m "Create DotPulsar pre-release dir" https://dist.apache.org/repos/dist/dev/pulsar/pulsar-dotpulsar-$DOTPULSAR_VERSION_RC
+svn co https://dist.apache.org/repos/dist/dev/pulsar/pulsar-dotpulsar-$DOTPULSAR_VERSION_RC
+cd pulsar-dotpulsar-$DOTPULSAR_VERSION_RC
+```
+
+Copy the signed artifacts into the RC directory and commit
+
+```shell
+cp /path/to/pulsar-dotpulsar-$DOTPULSAR_VERSION-src.* .
+svn add *
+svn ci -m 'Staging artifacts and signature for DotPulsar $DOTPULSAR_VERSION_RC'
+```
+
+5. Voting Process Execution.
+
+Send an email to the Pulsar Dev mailing list:
+
+```
+To: dev@pulsar.apache.org
+Subject: [VOTE] DotPulsar Release $DOTPULSAR_VERSION_RC
+
+Hi everyone,
+
+Please review and vote on the release candidate $N for the version $DOTPULSAR_VERSION, as follows:
+
+[ ] +1, Approve the release
+[ ] -1, Do not approve the release (please provide specific comments)
+
+DotPulsar's KEYS file contains the PGP keys we used to sign this release:
+https://downloads.apache.org/pulsar/KEYS
+
+Please download these packages and review this release candidate:
+- Review release notes
+- Download the source package (verify shasum, and asc) and follow the
+README.md to build and run DotPulsar.
+
+The vote will be open for at least 72 hours. It is adopted by majority approval, with at least 3 PMC affirmative votes.
+
+Source file:
+https://dist.apache.org/repos/dist/dev/pulsar/pulsar-dotpulsar-$DOTPULSAR_VERSION_RC/
+
+Nuget package:
+https://www.nuget.org/packages/DotPulsar/$DOTPULSAR_VERSION_RC
+
+The tag to be voted upon:
+https://github.com/apache/pulsar-dotpulsar/tree/$DOTPULSAR_VERSION_RC
+
+SHA-512 checksums:
+97bb1000f70011e9a585186590e0688586590e09 pulsar-dotpulsar-$DOTPULSAR_VERSION-src.tar.gz
+```
+
+The vote should be open for at least 72 hours (3 days). Votes from Pulsar PMC members will be considered binding, while anyone else is encouraged to verify the release and vote as well.
+
+If the release is approved here, we can then proceed to the next step.
+
+6. Vote Summary.
+
+```
+To: dev@pulsar.apache.org
+Subject: [RESULT][VOTE] Apache Pulsar DotPulsar $DOTPULSAR_VERSION released
+
+[RESULT][VOTE] Release Apache DotPulsar $DOTPULSAR_VERSION
+
+The vote to release Apache DotPulsar $DOTPULSAR_VERSION has passed.
+
+The vote PASSED with xxx binding +1 and 0 -1 votes:
+
+Binding votes:
+- Yuan Wang
+- tison
+- hulk
+- Liang Chen
+- Jean-Baptiste Onofré
+- Xiaoqiao He
+- donghui liu
+
+Vote thread:
+
+https://lists.apache.org/thread/XXX
+
+Thank you to all the above members for helping us to verify and vote for the $DOTPULSAR_VERSION release.
+
+Thanks
+```
+
+7. Release Artifacts.
+
+Promote the artifacts on the release location (need PMC permissions):
+
+```shell
+svn move -m "release $DOTPULSAR_VERSION" https://dist.apache.org/repos/dist/dev/pulsar/pulsar-dotpulsar-$DOTPULSAR_VERSION_RC \
+ https://dist.apache.org/repos/dist/release/pulsar/pulsar-dotpulsar-$DOTPULSAR_VERSION
+```
+
+Remove the old releases (if any). We only need the latest release there, older releases are available through the Apache archive.
+
+Get the list of releases:
+
+```shell
+svn ls https://dist.apache.org/repos/dist/release/pulsar | grep dotpulsar
+```
+
+Delete each release (except for the last one):
+
+```shell
+svn rm https://dist.apache.org/repos/dist/release/pulsar/pulsar-dotpulsar/<old-releases>
+```
+
+8. GitHub Release Creation.
+
+Browse to https://github.com/apache/pulsar-dotpulsar/releases/new
+
+If the head of the master branch has moved and therefore the last commit is not named `Make ready for release $DOTPULSAR_VERSION_RC`.
+Then change the Target from master to Recent Commits that matches `Make ready for release $DOTPULSAR_VERSION_RC`
+
+Create a tag `$DOTPULSAR_VERSION`.
+
+Create a release title: `DotPulsar $DOTPULSAR_VERSION`
+
+Visit https://github.com/apache/pulsar-dotpulsar/releases/edit/$DOTPULSAR_VERSION_RC. Proceed to extract the release notes from that specific version and seamlessly insert them into the final release.
+
+Make sure the `Set as the latest release` checkbox is checked!
+
+9. Release Announcement.
+
+Once the release process is available, you can announce the release and send an email as below:
+
+```
+To: dev@pulsar.apache.org, users@pulsar.apache.org, announce@apache.org
+Subject: [ANNOUNCE] Apache Pulsar C# Client DotPulsar $DOTPULSAR_VERSION released
+
+The Apache Pulsar team is proud to announce DotPulsar version $DOTPULSAR_VERSION.
+
+Pulsar is a highly scalable, low-latency messaging platform running on
+commodity hardware. It provides simple pub-sub semantics over topics,
+guaranteed at least once delivery of messages, automatic cursor management for
+subscribers, and cross-datacenter replication.
+
+For Pulsar release details and downloads, visit:
+https://github.com/apache/pulsar-dotpulsar/releases/tag/X.X.X
+
+Nuget package:
+https://www.nuget.org/packages/DotPulsar/X.X.X
+
+Release Notes are at:
+https://github.com/apache/pulsar-dotpulsar/blob/master/CHANGELOG.md
+
+We would like to thank the contributors who made the release possible.
+
+Regards,
+
+The Pulsar Team
+```