From e09469d26f9bfa1a0865d120183fd7eea06fe88f Mon Sep 17 00:00:00 2001
From: Yordis Prieto <yordis.prieto@gmail.com>
Date: Tue, 28 Oct 2025 13:15:31 -0400
Subject: [PATCH] chore: add fork diff explanation

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
---
 README.md                               |  3 +
 guides/explanations/fork-differences.md | 85 +++++++++++++++++++++++++
 2 files changed, 88 insertions(+)
 create mode 100644 guides/explanations/fork-differences.md

diff --git a/README.md b/README.md
index 73e0fd23..63f97d01 100644
--- a/README.md
+++ b/README.md
@@ -32,3 +32,6 @@ the Explanations, API Reference, How-To's and Tutorials guides.
 `Commanded` is based on [github.com/commanded/commanded](https://github.com/commanded/commanded).
 This fork introduces new features with an independent release cycle, allowing
 for thorough testing before contributing back to the original project.
+
+**See [Fork Differences](guides/explanations/fork-differences.md) for a complete
+list of changes and new features compared to the upstream repository.**
diff --git a/guides/explanations/fork-differences.md b/guides/explanations/fork-differences.md
new file mode 100644
index 00000000..7d085f8c
--- /dev/null
+++ b/guides/explanations/fork-differences.md
@@ -0,0 +1,85 @@
+# Fork Differences from Upstream
+
+This document tracks all changes made in the `straw-hat-team/commanded` fork compared to the upstream `commanded/commanded` repository.
+
+## Overview
+
+This fork maintains an independent release cycle to introduce new features and improvements with thorough testing before considering contributions back to the original project.
+
+**Upstream Repository:** [github.com/commanded/commanded](https://github.com/commanded/commanded)
+**Fork Repository:** [github.com/straw-hat-team/commanded](https://github.com/straw-hat-team/commanded)
+
+---
+
+## Breaking Changes
+
+### **Removed ProcessManager Support** ❌
+[PR #24](https://github.com/straw-hat-team/commanded/pull/24)
+
+**Changes:**
+- Removed all ProcessManager modules and tests
+- Removed ProcessManager documentation
+- Removed ProcessManager configuration
+- Updated documentation to remove ProcessManager references
+
+**Reason:** The saga pattern can be achieved using event handlers with read models and aggregates, eliminating the need for the additional ProcessManager abstraction.
+
+---
+
+### **EnrichedMetadata Struct** 🔄
+[PR #11](https://github.com/straw-hat-team/commanded/pull/11)
+
+**Changes:**
+- Replaced plain map metadata with `Commanded.EventStore.EnrichedMetadata` struct
+- Updated event handlers to use struct
+
+**Breaking:** Event handler callbacks now receive `%EnrichedMetadata{}` instead of a plain map.
+
+---
+
+## Features Added
+
+### **UUIDv7 Support** ✨
+[PR #22](https://github.com/straw-hat-team/commanded/pull/22)
+
+**Changes:**
+- Added UUIDv7 generation support for command and event IDs
+- Modified command router to use `UUID.uuid7/0` by default
+
+---
+
+### **Configurable UUID Provider** ✨
+
+**Changes:**
+- Integrated `Uniq.UUID` library for UUID generation
+- Made UUID provider configurable
+- Simplified UUID module by delegating to Uniq
+
+---
+
+### **Aggregate Telemetry for Version Conflicts** ✨
+[PR #8](https://github.com/straw-hat-team/commanded/pull/8)
+
+**Changes:**
+- Added telemetry events for wrong expected version errors in aggregates
+- Enhanced monitoring capabilities for version conflicts
+
+---
+
+### **Custom Event ID Support** ✨
+[PR #2](https://github.com/straw-hat-team/commanded/pull/2)
+
+**Changes:**
+- Added `Commanded.Event.EventId` protocol
+- Ability to set custom event IDs from event structs
+- Support for deterministic event IDs
+
+---
+
+### **EventStore Adapter** ✨
+[PR #1](https://github.com/straw-hat-team/commanded/pull/1)
+
+**Changes:**
+- Bundled `Commanded.EventStore.Adapters.EventStore` directly into Commanded
+- Eliminates need for separate `commanded_eventstore_adapter` package dependency
+