RFC categories / structure

Vac
1

This forum post suggests a structure for WAKU RFCs that, imho, would help new developers filtering and digesting the information quicker.
What do you think?

Adding a Category: Standard / Informational

I would suggest introducing categories for WAKU RFCs similar to RFC1796.

A first suggestion would be:

  • category: WAKU standard
    • documents containing normative specification of WAKU protocols
    • these documents are the basis for implementations
    • Waku2 implementations support a protocol if they adhere to the respective WAKU standard specifications
  • category: WAKU informational
    • documents providing valuable but not normative information
  • category: WAKU BCP
    • best current practice
    • these documents describe suggestions for (practical) integration of Waku specifications
      • e.g. a document describing which specifications are sensible for a mobile node to implement, and if available, which configuration options a mobile node might want to choose

We could also just introduce the first two categories and treat everything that is not WAKU standard as WAKU informational to keep it simple.

Categorizing References into Normative / Informative

I would suggest dividing references into two categories as described in
RFC3967:

Within an RFC, references to other documents fall into two general
categories: “normative” and “informative”. Broadly speaking, a
normative reference specifies a document that must be read to fully
understand or implement the subject matter in the new RFC, or whose
contents are effectively part of the new RFC, as its omission would
leave the new RFC incompletely specified. An informative reference
is not normative; rather, it provides only additional background
information.

Imho, this would further help streamlining the process of getting to know a specification,
as it makes clear which references are crucial for a compatible implementation.

Suggested Structure Within “Standards Track” Specifications

I would suggest the following structure for WAKU standard RFCs.
This draft RR demonstrates the suggested structure.
(Documents of other categories would not be subject to this structure.)

Specifically, I suggest moving the security/privacy considerations to the end.
Even given security/privacy is the focus of Waku, imho a specification document is easier to comprehend
if it first covers a motivation/rationale followed by theory/semantics and wire-format/syntax.
After having understood these parts, the security implications are easier to comprehend.

Further, having separate theory/semantics and syntax/wire-format sections should help grasping the gist of the specification quicker, and also states more clearly which parts must be implemented in a specific way.

Generally, I think, having a common structure makes orienting oneself easier.

Suggested Roadmap for Adaption

We could start using this scheme for new RFCs and update the WAKU standard RFCs accordingly before publishing WAKU2 v1.0.

2 Likes
2

Thanks for this, @ksr. I agree that a more structured approach to our RFCs will go a long way to communicate our protocols more clearly.

Initial comments on some of the above:

Adding a Category: Standard / Informational

These categories make sense to me, and I can’t currently think of any RFCs that won’t fit fairly easily into one of these. Most of our current RFCs would be standard or informational, but I can think of a couple that could be seen as bcp, such as our topic or peer recommendations. Perhaps a shorter handle for each category, e.g. waku_info, waku_std, waku_bcp?

Categorizing References into Normative / Informative

Maybe I need to think about this more, but I’m wondering how clear-cut this will be in some cases. E.g. is understanding the basics of publish-subscribe patterns a necessary part of the filter spec? I’d say it’s foundational knowledge, but the spec should be able to stand on its own without having read a separate doc on pub/sub. This would probably make any pub/sub reference informative within the filter spec context, but I’m not sure. I’ll mull this over a bit more.

Suggested Structure Within “Standards Track” Specifications

I roughly agree with the sections here and the rationale behind them. The PR also leaves room for “Further Optional Sections”, which provides some flexibility for different types of protocols. I also like the idea of having “Implementation Suggestions” as part of the main spec. According to your section definitions then, a call flow diagram/description would be “theory/semantics”, whereas message definitions are “wire-format/syntax”?

3

@ksr Please note some effort has already been started: https://github.com/vacp2p/rfc/issues/368

4

  1. rename the RFC category “Best Current Practice” to “Implementation Details”.

  2. Pick a tag to have a “type/subtype” structure value like MIME types that would require “registering” the first value, and allow the specification author to free-form the second. Eventually codify practice for the second.

So

tags: waku-application

might become

tags: waku/application
1 Like
5

We continued working on this during the offfsite.
The RFC template has been updated: add: draft RFC template by kaiserd · Pull Request #488 · vacp2p/rfc · GitHub

The result of the offsite discussion was using category as a MUST and tags as a “MAY”.
There are only three categories: Standards Track, Informational, Best Current Practice,
which makes assigning categories strait-forward.

1 Like