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.

Author: findleyr

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.

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.

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.

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.
 //

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.