libp2p / libp2p/specs

Discuss: Move away from semver for protocol versioning

Open
#203 4 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
No language data
Stars
1.8k
Forks
320
Avg merge
11d 15h
Merged PRs (30d)
1

Description

We have discussed this in various contexts. I believe the discussion deserves larger visibility.

I documented my rationale in the Ethereum 2.0 networking spec. Copying (with editorial fixes):

Why do we version protocol strings with ordinals instead of semver?

Using semver for network protocols is confusing. It is never clear what a change in a field, even if backwards compatible on deserialisation, actually implies. Network protocol agreement should be explicit. Imagine two peers:

  • Peer A supporting v1.1.1 of protocol X.
  • Peer B supporting v1.1.2 of protocol X.

These two peers should never speak to each other because the results can be unpredictable. This is an oversimplification: imagine the same problem with a set of 10 possible > versions. We now have 10^2 (100) possible outcomes that peers need to model for. The resulting complexity is unwieldy.

For this reason, we rely on negotiation of explicit, verbatim protocols. In the above case, peer B could provide backwards compatibility by supporting and advertising both v1.1.1 and v1.1.2 of the protocol.

Under this scenario, semver would be relegated to convey expectations at the human level, and it wouldn't do a good job there either, because it's unclear if "backwards-compatibility" and "breaking change" apply only to wire schema level, to behaviour, state machine, etc.

Therefore, we remove semver out of the picture and replace it with ordinals that require explicit agreement, and do not mandate a specific policy for changes.

I'm personally for this change. Curious to hear from others.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read the rationale copied from the Ethereum 2.0 networking spec PR #1328 and review the four-comment discussion. Before implementation, reach agreement on whether protocol version strings should use explicit ordinals instead of semver and define the affected specifications and acceptance criteria; the issue names no files or tests.

Written by the indexing model from the issue text.

Assessment

Domain
distributed-systems, networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.