search

libp2p / specs

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

Proposal: Introduce spec numbers #566

Open MarcoPolo opened 1 year ago

MarcoPolo commented 1 year ago

This has come up a couple of times, and also brought up by Juan at a recent libp2p sync.

The idea is that we should be able to reference specific specs by a number. I'm currently imagining doing the same thing IPFS does with its proposals, which is to number them by the PR number that introduced the change. I like this for two reasons:

  1. Backwards compatible. All existing specs automatically have a number.
  2. Meaningful. The numbers are not an arbitrary point in time, but rather a pointer you can use to learn more about the context around the changes (github.com/libp2p/specs/pull/ or going through the Git history). While a spec should stand on its own, sometimes it is useful to understand the context around a change.

In libp2p's history, we had a brief ~2 month period where we attempted to use the traditional RFC numbering system. That hasn't worked out in practice. Only 3 documents have adopted that format.

While a number isn't required, it does allow us to be more specific when we talk about certain specs. As an example, consider how vague "HTTP semantics" or "HTTP Authentication" is (RFC 2617, 7617, 9110, or something else?), and consider how precise "RFC 9110 HTTP Semantics" and "RFC 9110 HTTP Authentication" is. I want to be able to refer to things like "HTTP Peer ID authentication #564" and be as precise.

I'm curious to hear if folks have strong opinions against this.

thomaseizinger commented 1 year ago

Big support from my end. One thing I'd like to stress is that having a number doesn't mean we should think of good names for things.

Many times, protocols or specs need some kind of identifier when implemented. Your referenced HTTP Authentication for example needs a name for the WWW-Authenticate and Authorization header.

That is effectively also the name for your spec. It is the Libp2p-PeerId HTTP authentication scheme. There can't be a 2nd one because it would be ambiguous in software.

I do think that spec numbers are a good idea. I'd love for the RFC stuff to be cleaned up if we do this :)

How would we deal with (backwards-compatible) updates to specs when using PR numbers? Always reference them by the first PR that introduced it?