From 4df68b2eac918bfb421c9609d853b4a0e9b963f2 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sun, 22 Feb 2026 17:20:04 +0000
Subject: [PATCH] Add v4.0 migration notes to README and docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README.md: add 'Version 4.0 — BCL IAsyncEnumerable Compatibility' section
  explaining the type alias, zero-cost interop, and how to migrate from v3.x
- docs/index.md: add v4 callout with migration link
- docs/AsyncSeq.fsx: add v4 note explaining IAsyncEnumerable<'T> interop

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 README.md         | 12 ++++++++++++
 docs/AsyncSeq.fsx |  4 ++++
 docs/index.md     |  7 ++++++-
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 257afbe..c0ed874 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,18 @@
 See [the home page](http://fsprojects.github.io/FSharp.Control.AsyncSeq/) for details. The home page can be [edited, forked or cloned](https://github.com/fsprojects/FSharp.Control.AsyncSeq/tree/master/docs/content)
 Please contribute to this project. Don't ask for permission, just fork the repository and send pull requests.
 
+## Version 4.0 — BCL IAsyncEnumerable Compatibility
+
+As of **v4.0**, `AsyncSeq<'T>` is a type alias for `System.Collections.Generic.IAsyncEnumerable<'T>` (the BCL type). This means:
+
+- `AsyncSeq<'T>` values are directly usable anywhere `IAsyncEnumerable<'T>` is expected (e.g. `await foreach` in C#, `IAsyncEnumerable<T>` APIs).
+- `IAsyncEnumerable<'T>` values (from EF Core, ASP.NET Core streaming endpoints, etc.) can be used directly wherever `AsyncSeq<'T>` is expected — no conversion needed.
+- The `AsyncSeq.ofAsyncEnum` and `AsyncSeq.toAsyncEnum` helpers are now **no-ops** and have been marked `[<Obsolete>]`. Remove any calls to them.
+
+### Migrating from v3.x
+
+If you called `.GetEnumerator()` / `.MoveNext()` directly on an `AsyncSeq<'T>`, update to `.GetAsyncEnumerator(ct)` / `.MoveNextAsync()` (the `IAsyncEnumerator<'T>` BCL contract). All other `AsyncSeq` module combinators are unchanged.
+
 # Maintainer(s)
 
 - [@dsyme](https://github.com/dsyme)
diff --git a/docs/AsyncSeq.fsx b/docs/AsyncSeq.fsx
index 611b2ca..409d99c 100644
--- a/docs/AsyncSeq.fsx
+++ b/docs/AsyncSeq.fsx
@@ -26,6 +26,10 @@ latter based on a "synchronous push". Analogs for most operations defined for `S
 `AsyncSeq`. The power of `AsyncSeq` lies in that many of these operations also have analogs based on `Async` 
 allowing composition of complex asynchronous workflows.
 
+> **v4.0 and later:** `AsyncSeq<'T>` is a type alias for `System.Collections.Generic.IAsyncEnumerable<'T>`.
+> Any `IAsyncEnumerable<'T>` value (e.g. from EF Core, ASP.NET Core channels, or `taskSeq { }`) can be used
+> directly as an `AsyncSeq<'T>` without conversion, and vice-versa.
+
 The `AsyncSeq` type is located in the `FSharp.Control.AsyncSeq.dll` assembly which can be loaded in F# Interactive as follows:
 *)
 
diff --git a/docs/index.md b/docs/index.md
index bf8f3bb..ee9f26c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,10 +3,15 @@ FSharp.Control.AsyncSeq
 
 FSharp.Control.AsyncSeq is a collection of asynchronous programming utilities for F#.
 
-An AsyncSeq is a sequence in which individual elements are retrieved using an `Async` computation.
+An `AsyncSeq<'T>` is a sequence in which individual elements are retrieved using an `Async` computation.
 The power of `AsyncSeq` lies in that many of these operations also have analogs based on `Async` 
 allowing composition of complex asynchronous workflows, including compositional cancellation.
 
+> **v4.0:** `AsyncSeq<'T>` is now a type alias for `System.Collections.Generic.IAsyncEnumerable<'T>`.
+> Values flow freely between `AsyncSeq<'T>` and `IAsyncEnumerable<'T>` without any conversion.
+> `AsyncSeq.ofAsyncEnum` / `AsyncSeq.toAsyncEnum` are now no-ops and marked obsolete — remove them.
+> See the [README](https://github.com/fsprojects/FSharp.Control.AsyncSeq#version-40--bcl-iasyncenumerable-compatibility) for migration notes.
+
 An `AsyncSeq<'a>` can be generated using computation expression syntax much like `seq<'a>`:
 
     let oneThenTwo = asyncSeq {