Proposal: Introduce spec numbers
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 1.8k
- Forks
- 320
- Avg merge
- 11d 15h
- Merged PRs (30d)
- 1
Description
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:
- Backwards compatible. All existing specs automatically have a number.
- 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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the existing RFC directory, the three documents using its format, and the linked IPFS proposal for numbering conventions. Check the repository history and pull requests to understand how existing specs could be referenced. Done would require an agreed numbering approach and a clear plan for applying it to the specifications.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100