add: draft RFC template #488

kaiserd · 2022-02-12T16:49:43Z

This draft PR demonstrates an example structure for RFCs of the WAKU standard category as described in this forum post.

jm-clius · 2022-02-14T14:12:02Z

I've commented on the wider issue of RFC structuring here: https://forum.vac.dev/t/rfc-categories-structure/125

D4nte · 2022-02-18T03:59:49Z

content/docs/rfcs/42/README.md

+title: 42/WAKU2-STANDARD-Template
+name: Waku v2 Stadard Template
+status: raw
+category: WAKU standard


We use tags not category: https://rfc.vac.dev/spec/1/#appendix-b-metainformation

discussed during offsite, let's use categories a la IETF

Tags can be used as optional meta information but shouldn't be imposed as it creates complexity/overhead and there also doesn't seem to be a good precedence for it in specs world (IETF etc)

We'd have to update the 1 RFC to introduce the category.

kaiserd · 2022-07-16T14:55:57Z

Updated as per our off-site discussion. This would make tagging, as introduced #368, optional.

An alternative/addition to tagging for clarifying the usage of various protocols are BCP (best common practice) RFCs.

kaiserd · 2022-07-16T14:57:44Z

We could add further information about writing RFCs in the README.md

jm-clius

This LGTM! Thanks. Will go a long way to make our RFCs more standardised and readable.

jm-clius · 2022-07-19T10:24:31Z

content/docs/rfcs/template/README.md

@@ -0,0 +1,62 @@
+---
+slug: XX
+title: XX/(WAKU2|LOGOS|CODEX|...)-TEMPLATE


Assuming RFCs that does not belong to a single project or applies to several (e.g. "RLN" without relay) would just not use a prefix at all?

We could make the prefix optional (i.e. not mentioning it in the template at all).
Or, we could list a set of "known" prefixes, but also allow further prefixes / prefix-less RFCs.
The [...] could be replaced by "*": any or no prefix. README could explain this.
wdyt?

Sounds good to me! Don't think we need too overexplain this - a "*" would fully indicate the meaning, I think.

We might differentiate between project's specific RFCs from general RFC (that apply to several projects) with a notation like
XX/WAKU2/A-TEMPLATE <- specific to WAKU2
XX/ANOTHER-TEMPLATE <- multi project
This avoids the double meaning of the "-" which separates prefix and suffix, but also multi-words suffixes.

I like that :).
What I did in the template was to be backwards compatible. But... I'd have to update the RFCs adding the category anyway. Ill put that into the restructure issue (yet to be opened, see #513)

Hm, I'm worried this complicates things? The optional prefix seems like most minimal KISS.

Do we have an example of some spec project using double namespacing? E.g. //.

What do we hope to gain from this, vs more informal prefix?

jm-clius · 2022-07-19T10:26:37Z

content/docs/rfcs/template/README.md

+
+# Wire Format Specification / Syntax
+
+A standard track RFC must feature this section.


Perhaps only when in draft or higher? Perhaps we may want to relax requirements for raw RFCs so we can standardise a bit quicker on semantics even if wire format is not yet fleshed out?

Yes. The the MUSTs are for "stable". Raw and draft "should". Done in 4186eb8.

jm-clius · 2022-07-19T10:27:43Z

content/docs/rfcs/template/README.md

+A standard track RFC must feature this section.
+This section SHOULD not contain explanations of semantics and focus on concisely defining the wire format.
+Implementations MUST adhere to these exact formats to interoperate with other implementations.
+It is fine, if parts of the previous section that touch on the wire format are repeated.


I like this. This section is in other words the TL;DR for implementers.

Yes. An implementor who already understand the basic functioning and background of a protocol can go to this section directly.

kaiserd · 2022-07-19T11:03:41Z

I added a meta section for explaining things about the process of writing RFCs (it also links COSS).
For now it explains tags as introduced in #368
Also using the tag path structure suggested by @easye in the forum discussion https://forum.vac.dev/t/rfc-categories-structure/125/3
Wdyt?

content/docs/rfcs/template/README.md

oskarth · 2022-07-22T05:42:42Z

content/docs/rfcs/template/README.md

+contributors:
+---
+
+# (Info, remove this section)


I wonder, should this be a template or in itself a spec? :D

I could remove this and put things into COSS exclusively.
However, Imo, like this the template is self-contained and I would add the info to COSS as well anyways.
(see my comment above). Could also change this in a future PR. Wdyt?

oskarth

LGTM, and this will be helpful to spec writers!

s1fr0

LGTM too! Great standardization job! I left a comment regarding how we can possibly differentiate between project-specific and general RFCs.

kaiserd · 2022-07-22T15:09:24Z

Further opinions on @s1fr0 suggestion? I like that. My comment inline

- see RFC 29

* master: RFC16: add version call (#505) fix(noise): update RFC to implementation (#508) fixup: 37/WAKU2-NOISE fix images paths (#506) New RFC: 37/WAKU2-NOISE-SESSIONS (#504) 36/WAKU2-BINDINGS-API (#501) docs(16/WAKU2-RPC): add ENR to waku info (#502) Adding 35/WAKU2-NOISE to menu (#500) add RFC33 to index (#499) feat: 32/RLN raw spec New RFC: 35/WAKU2-NOISE (#496) Update on the rln registration figure to match the current spec (#497) 33/WAKU-DISCV5: Add first raw version (#487) Add pubsubTopic field to index (#492) Fix markdown links (#493) Categorize 22 & 31 (#490) Changed PB Timestamp index to 10 (#491) 13/14/16/21: Change in timestamp format (#483) add: RFC31 copyright statement (#489) 17/WAKU-RLN-RELAY: Revise spec for its draft version (#484)

kaiserd · 2022-07-25T11:13:28Z

(The merge commit done by via Github was not signed, so I had to rebase and force commit.)

oskarth added this to New in vac-research Feb 12, 2022

oskarth moved this from New to Review/QA in vac-research Feb 12, 2022

kaiserd requested review from jm-clius, oskarth, s1fr0 and staheri14 February 12, 2022 16:50

kaiserd self-assigned this Feb 12, 2022

D4nte reviewed Feb 18, 2022

View reviewed changes

kaiserd mentioned this pull request Jul 1, 2022

38/LOGOS-CONSENSUS-GLACIER #512

Merged

kaiserd marked this pull request as ready for review July 16, 2022 14:56

kaiserd requested a review from D4nte July 16, 2022 14:56

kaiserd mentioned this pull request Jul 16, 2022

RFC template #513

Closed

2 tasks

jm-clius approved these changes Jul 19, 2022

View reviewed changes

oskarth reviewed Jul 22, 2022

View reviewed changes

content/docs/rfcs/template/README.md Show resolved Hide resolved

oskarth reviewed Jul 22, 2022

View reviewed changes

content/docs/rfcs/template/README.md Show resolved Hide resolved

oskarth reviewed Jul 22, 2022

View reviewed changes

oskarth approved these changes Jul 22, 2022

View reviewed changes

s1fr0 approved these changes Jul 22, 2022

View reviewed changes

kaiserd added 7 commits July 25, 2022 13:10

add: draft RFC template

2fc3dec

move slug / fix name

5d8910f

add: copyright

1fcf1da

copyright before references

eff7da4

- see RFC 29

fix: remove double copyright

931d5aa

update

e9e762a

kaiserd added 4 commits July 25, 2022 13:10

use exact IETF category wording

a1b825e

address feedback

9833de3

add feeback

09033dd

add meta section

00bdd51

kaiserd force-pushed the add/waku-rfc-template branch from 8af9bb6 to 00bdd51 Compare July 25, 2022 11:11

kaiserd merged commit cc3f4ee into master Jul 25, 2022

vac-research automation moved this from Review/QA to Done Jul 25, 2022

kaiserd deleted the add/waku-rfc-template branch July 25, 2022 11:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add: draft RFC template #488

add: draft RFC template #488

kaiserd commented Feb 12, 2022

jm-clius commented Feb 14, 2022

D4nte Feb 18, 2022

oskarth Jul 16, 2022

kaiserd Jul 16, 2022 •

edited

kaiserd commented Jul 16, 2022

kaiserd commented Jul 16, 2022

jm-clius left a comment

jm-clius Jul 19, 2022

kaiserd Jul 19, 2022

jm-clius Jul 19, 2022

kaiserd Jul 19, 2022

s1fr0 Jul 22, 2022

kaiserd Jul 22, 2022

oskarth Jul 25, 2022

jm-clius Jul 19, 2022

kaiserd Jul 19, 2022 •

edited

jm-clius Jul 19, 2022

kaiserd Jul 19, 2022

kaiserd commented Jul 19, 2022 •

edited

oskarth Jul 22, 2022

kaiserd Jul 22, 2022

oskarth left a comment

s1fr0 left a comment

kaiserd commented Jul 22, 2022 •

edited

kaiserd commented Jul 25, 2022


		# Wire Format Specification / Syntax

		A standard track RFC must feature this section.

add: draft RFC template #488

add: draft RFC template #488

Conversation

kaiserd commented Feb 12, 2022

jm-clius commented Feb 14, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kaiserd Jul 16, 2022 • edited

Choose a reason for hiding this comment

kaiserd commented Jul 16, 2022

kaiserd commented Jul 16, 2022

jm-clius left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kaiserd Jul 19, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kaiserd commented Jul 19, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oskarth left a comment

Choose a reason for hiding this comment

s1fr0 left a comment

Choose a reason for hiding this comment

kaiserd commented Jul 22, 2022 • edited

kaiserd commented Jul 25, 2022

kaiserd Jul 16, 2022 •

edited

kaiserd Jul 19, 2022 •

edited

kaiserd commented Jul 19, 2022 •

edited

kaiserd commented Jul 22, 2022 •

edited