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.
This commit is contained in:
parent
72afbc91bd
commit
32d84d8421
5 changed files with 36 additions and 0 deletions
|
|
@ -38,3 +38,9 @@ protocol.
|
||||||
# TroubleShooting
|
# TroubleShooting
|
||||||
|
|
||||||
See [troubleshooting.md](troubleshooting.md) for a troubleshooting guide.
|
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.
|
||||||
|
|
|
||||||
12
docs/rough_edges.md
Normal file
12
docs/rough_edges.md
Normal file
|
|
@ -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.
|
||||||
|
|
@ -37,3 +37,9 @@ protocol.
|
||||||
# TroubleShooting
|
# TroubleShooting
|
||||||
|
|
||||||
See [troubleshooting.md](troubleshooting.md) for a troubleshooting guide.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -8,6 +8,7 @@
|
||||||
//go:generate weave -o ../../docs/client.md ./client.src.md
|
//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/server.md ./server.src.md
|
||||||
//go:generate weave -o ../../docs/troubleshooting.md ./troubleshooting.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.
|
// The doc package generates the documentation at /doc, via go:generate.
|
||||||
//
|
//
|
||||||
|
|
|
||||||
11
internal/docs/rough_edges.src.md
Normal file
11
internal/docs/rough_edges.src.md
Normal file
|
|
@ -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.
|
||||||
Loading…
Reference in a new issue