From 32d84d8421b315633f070246a0833531489cf77f Mon Sep 17 00:00:00 2001
From: Robert Findley <rfindley@google.com>
Date: Wed, 29 Oct 2025 10:57:45 -0400
Subject: [PATCH] docs: document known rough edges (#609)

Start keeping a log of rough edges we've discovered post v1.0.0, so that
they're discoverable (along with their workarounds), and so that we can
fix them in v2.
---
 docs/README.md                   |  6 ++++++
 docs/rough_edges.md              | 12 ++++++++++++
 internal/docs/README.src.md      |  6 ++++++
 internal/docs/doc.go             |  1 +
 internal/docs/rough_edges.src.md | 11 +++++++++++
 5 files changed, 36 insertions(+)
 create mode 100644 docs/rough_edges.md
 create mode 100644 internal/docs/rough_edges.src.md

diff --git a/docs/README.md b/docs/README.md
index 9f32507..0e8259c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -38,3 +38,9 @@ protocol.
 # TroubleShooting
 
 See [troubleshooting.md](troubleshooting.md) for a troubleshooting guide.
+
+# Rough edges
+
+See [rough_edges.md](rough_edges.md) for a list of rough edges or API
+oversights that can't be addressed due to our compatibility promise. We'll
+revisit these if/when we move to a v2 of the SDK.
diff --git a/docs/rough_edges.md b/docs/rough_edges.md
new file mode 100644
index 0000000..7bb7732
--- /dev/null
+++ b/docs/rough_edges.md
@@ -0,0 +1,12 @@
+<!-- Autogenerated by weave; DO NOT EDIT -->
+# Rough edges: API decisions to reconsider for v2
+
+This file collects a list of API oversights or rough edges that we've uncovered
+post v1.0.0, along with their current workarounds. These issues can't be
+addressed without breaking backward compatibility, but we'll revisit them for
+v2.
+
+- `EventStore.Open` is unnecessary. This was an artifact of an earlier version
+  of the SDK where event persistence and delivery were combined.
+  
+  **Workaround**: `Open` may be implemented as a no-op.
diff --git a/internal/docs/README.src.md b/internal/docs/README.src.md
index 7f7b224..e70596b 100644
--- a/internal/docs/README.src.md
+++ b/internal/docs/README.src.md
@@ -37,3 +37,9 @@ protocol.
 # TroubleShooting
 
 See [troubleshooting.md](troubleshooting.md) for a troubleshooting guide.
+
+# Rough edges
+
+See [rough_edges.md](rough_edges.md) for a list of rough edges or API
+oversights that can't be addressed due to our compatibility promise. We'll
+revisit these if/when we move to a v2 of the SDK.
diff --git a/internal/docs/doc.go b/internal/docs/doc.go
index 7b23ad6..3d87686 100644
--- a/internal/docs/doc.go
+++ b/internal/docs/doc.go
@@ -8,6 +8,7 @@
 //go:generate weave -o ../../docs/client.md ./client.src.md
 //go:generate weave -o ../../docs/server.md ./server.src.md
 //go:generate weave -o ../../docs/troubleshooting.md ./troubleshooting.src.md
+//go:generate weave -o ../../docs/rough_edges.md ./rough_edges.src.md
 
 // The doc package generates the documentation at /doc, via go:generate.
 //
diff --git a/internal/docs/rough_edges.src.md b/internal/docs/rough_edges.src.md
new file mode 100644
index 0000000..150509b
--- /dev/null
+++ b/internal/docs/rough_edges.src.md
@@ -0,0 +1,11 @@
+# Rough edges: API decisions to reconsider for v2
+
+This file collects a list of API oversights or rough edges that we've uncovered
+post v1.0.0, along with their current workarounds. These issues can't be
+addressed without breaking backward compatibility, but we'll revisit them for
+v2.
+
+- `EventStore.Open` is unnecessary. This was an artifact of an earlier version
+  of the SDK where event persistence and delivery were combined.
+  
+  **Workaround**: `Open` may be implemented as a no-op.