search

libp2p / specs

Technical specifications for the libp2p networking stack
https://libp2p.io
1.56k stars 273 forks source link

revisit revisions #457

Open marten-seemann opened 2 years ago

marten-seemann commented 2 years ago

If I am not mistaken, a non-breaking change qualifies as a revision bump

Revision numbers start with lowercase r followed by an integer, which gets bumped whenever the spec is modified by merging a new PR.

https://github.com/libp2p/specs/blob/master/00-framework-02-document-header.md

Indeed, that's what the document says. We should change that. It doesn't make sense to bump the version for every change, e.g. in the extreme case fixing a typo.

Originally posted by @marten-seemann in https://github.com/libp2p/specs/issues/456#issuecomment-1252906980

MarcoPolo commented 2 years ago

Would semver here make sense? I think it's useful to differentiate between backward incompatible changes and small changes.

marten-seemann commented 2 years ago

I'd like to distinguish a few cases:

  1. trivial changes: easy rewording, typo fixes, etc. I don't think we need to change anything. This is only creating noise.
  2. backwards-compatible changes: e.g. adding a field to a Protobuf with optional functionality. In that case, a revision bump seems to make sense.
  3. backwards-incompatible changes: This effectively means standardizing a new protocol, and should live in a new document. There will still be nodes out there in the network speaking the old protocol version, and we shouldn't require people to go back in the Git history to understand how that version of the protocol works.