Thanks very much for kicking off what has turned into a great thread from the humble beginnings of [1] ;)
I've attempted to summarise it to distill the essence as there is a lot of detail:
- There seems to be general consensus that:
- 1.1.0 is better than 2.0.0.
- 1.1.0 is also better than 1.0.1.
By changing the minor number users can see it is more than a bugfix release, but we're arguably abusing the naming slightly by not bumping the major number.
That seeming abuse of semver is handled by a "get out of jail free card", namely that we haven't documented the gRPC protocol and hence implicitly haven't agreed (and documented) precisely what API breakage means yet.
We also need to remember to include details of the breakage in the release notes.
- Plan B:
It's worth mentioned that another thought we had yesterday was that we could revert the breaking change [2] to allow us to release a true 1.0.1.
That would give us breathing space to investigate the breakage more fully and find a way to avoid it happening in the future (or atleast detect and minimise).
== TODO list from this thread ==
I've raised a bunch of issues here and referenced some existing ones. Please dive in by commenting, emojifying, assigning to yourself (please! ;), etc:
- Jon plans to write up a slide deck on gRPC API evolution best practices (I'd love to see this! ;)
- We need to document the gRPC protocol:
- We need to version the gRPC protocol:
- We need to guarantee persistent state files are consumable by newer component versions:
- We need to update our documentation to explain that we cannot handle "live upgrade":
- We need to update our documentation to explain that all component versions must (currently) match for correct operation:
Cheers,
James