RFC006: Semantic Versioning #365
Conversation
cmwaters
requested review from
ebuchman,
josef-widder,
konnov and
milosevic
as code owners
This is a good question. This RFC, in a way, ties in how the different sub versions within Tendermint i.e. (ABCI, Block, & P2P) relate to the overall version. There's probably still value in keeping these sub versions as a means of mapping to the different user groups although I do like the idea of having one simple version to represent the state of Tendermint. |
Co-authored-by: M. J. Fromberger <fromberger@interchain.io>
|
If you update your branch, I think the lint errors should go away. 🙂 |
Well, they were all fixed. But since then more folks have checked in broken links 😞 We should either make that check required, or remove it. |
I vote make required, it's a simple check and should prevent some reasonably embarrassing issues. |
I agree, but we'll need to find someone with admin rights on the repository to change the branch protection rules. |
|
I also agree and have updated it accordingly |
rfc/006-semantic-versioning.md
Outdated
|
|
||
| We first begin with a round up of the various users and a set of assumptions on what these users expect from Tendermint in regards to versioning: | ||
|
|
||
| 1. **Application Developers**, those that use the ABCI to build applications on top of Tendermint, are chiefly concerned with that API. Breaking changes will force developers to modify large portions of their codebase to accommodate for the changes. Some ABCI changes such as introducing priority for the mempool don't require any effort and can be lazily adopted whilst changes like ABCI++ may force applications to redesign their entire execution system. |
There was a problem hiding this comment.
ABCI is also interesting in that which part counts as "the API" depends on context. For Go developers compiling directly, ABCI may be synonymous with the Go library APIs for ABCI; whereas external process applications see a wire protocol.
We don't need to go into depth in this document, but it might be worth calling out that it's the abstract ABCI protocol we are mainly concerned about here: The methods and messages and responses and their semantics. The way those are implemented in the Go libraries could change, provided the semantics remain the same. (This distinction will wind up being important as we work on the implementation, thinking here specifically of our plans around locking)
There was a problem hiding this comment.
[M]ay force applications to redesign their entire execution system.
Do I understand correctly, that an application using vanilla ABCI today would not have to change anything (or very little) to keep working? I thought part of the point of the ABCI++ design was that only applications that want to take advantage of the new stages would need to be reworked.
I think it's helpful to distinguish between "forced" and "unforced" changes, e.g., changes that I choose to make to get a new feature, better performance, etc., vs. changes I have to make regardless what I want.
There was a problem hiding this comment.
Where I was coming from when I wrote this statement is developers that want to upgrade to a new version. When you upgrade to v0.36, you'll get ABCI++ as part of it. You can not opt out of it and are "forced" to make changes to your application
There was a problem hiding this comment.
I think your distinction here in your earlier comment captures something I hadn't thought too much of. Which is that the surface application developers have when writing in Go is quite different to when writing in other languages and that we shouldn't look at just the ABCI interface but other things like the RPC which for example the CosmosSDK uses.
| A major version in Tendermint guarantees that for the entire cycle of that major version: | ||
|
|
||
| - All blocks and state data in a blockchain can be queried. All headers can be verified even across minor version changes. Nodes can both block sync and state sync from genesis to the head of the chain. | ||
| - Nodes in a network are able to communicate and perform BFT state machine replication so long as the agreed network version is the lowest of all nodes in a network. For example, nodes using version 1.5.x and 1.2.x can operate together so long as the network version is 1.2 or lower (but still within the 1.x range). This rule essentially captures the concept of network backwards compatibility. |
There was a problem hiding this comment.
I think it does answer my question. I'm trying to think about how to word this promise in a way that would avert my original confusion. Perhaps:
All nodes in a network operating at or above the agreed network version are able to communicate and perform BFT state replication.
Trying to get at the idea that the whole network doesn't stop just because one node is recalcitrant -- only the laggards get stuck. Maybe there's a better way to put that.
|
|
||
| For the entire cycle of a **minor version** in Tendermint: | ||
|
|
||
| - Public Go API's, for example in `node` or `abci` packages will not change in a way that requires any consumer (not just application developers) to modify their code. |
There was a problem hiding this comment.
The mild difficulty that I see this presenting is that Go's tooling will consider two versions 'compatible' within the same major version. Using the tooling to automatically grab the latest will now grab a version of the software that breaks compile. I don't have a huge objection to this, but it is a bit out of line with the way most go projects work.
There was a problem hiding this comment.
Agreed, but note below:
These guarantees will come into effect at release 1.0.
so I think we are safe. Possibly we should highlight that line at the top of the doc, though.
|
|
||
| ## Proposal | ||
|
|
||
| Tendermint version labels will follow the syntax of [Semantic Versions 2.0.0](https://semver.org/) with a major, minor and patch version. The version components will be interpreted according to these rules: |
There was a problem hiding this comment.
Should we clarify that patch releases are for bug fixes and security patches only and that new features will always accompany bumps to the minor version?
There was a problem hiding this comment.
Yeah that might make sense to add a short note about
Co-authored-by: M. J. Fromberger <fromberger@interchain.io> Co-authored-by: William Banfield <4561443+williambanfield@users.noreply.github.com>
This RFC is the first in a set of items relating to Tendermint's upgrading story. It tries to capture prior internal dicussions held on versioning in Tendermint.
Rendered