A new RFC for making RFCs? #10

Open
opened 2019-08-03 09:07:27 +00:00 by southerntofu · 4 comments

Following some discussions on #9, i feel like we need a discussion about the format and submission process for tildeverse RFCs.

Currently, the process is as follows to publish a draft:

  1. Create a Markdown file, preceded by YAML frontmatter following a format defined in RFC0
  2. Fork the tildeverse/rfcs repo
  3. Commit your draft
  4. Open a pull request

This process is good but there is imo no reason that contribution has to go through the Gitea forge.

Serialization/Deserialization for YAML/TOML/JSON is pretty straightforward, so i would propose that the RFC defines the data structure but proposes several representations of it without enforcing a single one.

Also, it would be good to open more ways to contribute RFCs, for example a mail gateway: a plaintext email sent to drafts@rfc.tildeverse.org where RFC draft title can be extracted from mail title and authorship info from From/CC field. A new mail from the same person with the same title would result in the draft being updated (or maybe it's not a good idea, i don't know)

These are just thoughts and is not a final proposal. I want to hear your feedback :)

Following some discussions on #9, i feel like we need a discussion about the format and submission process for tildeverse RFCs. Currently, the process is as follows to publish a draft: 1. Create a Markdown file, preceded by YAML frontmatter following a format defined in RFC0 2. Fork the tildeverse/rfcs repo 3. Commit your draft 4. Open a pull request This process is good but there is imo no reason that contribution has to go through the Gitea forge. Serialization/Deserialization for YAML/TOML/JSON is pretty straightforward, so i would propose that the RFC defines the data structure but proposes several representations of it without enforcing a single one. Also, it would be good to open more ways to contribute RFCs, for example a mail gateway: a plaintext email sent to drafts@rfc.tildeverse.org where RFC draft title can be extracted from mail title and authorship info from From/CC field. A new mail from the same person with the same title would result in the draft being updated (or maybe it's not a good idea, i don't know) These are just thoughts and is not a final proposal. I want to hear your feedback :)
Author

Also i would like to propose to add contribution metadata to the RFC format. Something along the lines of:

contribute-url: <URI>
contribute-type: git|mercurial|etherpad

I'm sure we can find prettier vocabulary for the data format, but i think it would be nice to add a « Contribute here » link on draft pages.

Also i would like to propose to add contribution metadata to the RFC format. Something along the lines of: ``` contribute-url: <URI> contribute-type: git|mercurial|etherpad ``` I'm sure we can find prettier vocabulary for the data format, but i think it would be nice to add a « Contribute here » link on draft pages.
Author

Some more thoughts.

drafts submodule

It would be nice to have a separate repo for drafts management, so we can version control drafts as well without polluting this repo's commit history. This repository would continue to serve for publishing accepted RFCs and maintaining the source of the rfc.tildeverse.org website.

The drafts repo would be added as a git submodule to this repository's content/drafts folder. This way, a draft RFC could be submitted as a PR on the drafts repo. Accepting the PR would be the moderation process for drafts.

Contribution by other individuals could take place:

  • before moderation on the source of the PR (eg. southerntofu/drafts, potentially on a specific branch)
  • after initial moderation on the tildeverse/drafts repo

So all discussions about future RFCs would as some point take place on the drafts repo. Following the drafts repo would therefore keep tilde members up to date on proposed standards for the tildeverse.

So the contribution pipeline for an RFC would look like this:

  1. Fork this repository
  2. Create a new branch for the RFC on the fork repo
  3. Commit your Markdown file
  4. Open a pull request on this repository
  5. Initial review takes place (to fend off spammers/trolls)
  6. Reviewers propose changes on the PR discussion.
  7. External contributors propose changes as issues/PRs on the fork
  8. Reviewers merge the PR; draft gets rendered on the website
  9. People link to the RFC draft, have discussions, propose changes on tildeverse/drafts in the form of issues/PRs
  10. When contributors feel like their proposal is ready for final review, they open a PR on this repository, assigning it the next-available RFC number
  11. Final review takes place
  12. additional patches can be merged on the drafts repo to keep the public draft page updated
  13. When the proposal is finally ready, it is merged by reviewers

Dependency graph

Some semantics should allow to express that an RFC depends on another. More precisely, that implementing an RFC cannot be achieved without implementing those other "required" RFCs.

For example, consider a Tor RFC and a webmention RFC. Implementing a webmention over Tor RFC would require implementing the Tor RFC and the webmention RFC.

Concretely, this allows to present in a human-friendly manner information about required steps before implementing an RFC.

Implementation status code

We could define an implementation status code for RFCs. We assume here that we have some form of optional "Recommendations" section defined in the RFC format, where every sub-item is an individual recommendation that persons implementing the RFC MAY implement if they wish.

To compute the status code, we consider a sequence of bits. Where n is the number of recommendations (second-level headings contained within the Recommendations first-level heading), our sequence contains n bits all initialized to 0. For each recommendation, if it is implemented by the tilde server, the corresponding bit is set to 1. The binary number is then turned to a decimal representation which is the implementation status code

for example for a RFC with two recommendations. Here's the list of possible combinations:

  • none implemented -> 00 -> 0
  • implemented 1 -> 10 -> 2
  • implemented 2 -> 01 -> 1
  • implemented 1 & 2 -> 11 -> 3

Note: this works because the number of recommendations does not change over time. RFC is not edited, but replaced by another RFC.

This would allow tilde operators (and other people) to semantically and visually present information about the server's capabilities in regards to tildeverse standards.

For example, tildeverse.org could (for the sake of argument) maintain a list of pratchett-friendly servers supporting RFC1.

Some more thoughts. ## drafts submodule It would be nice to have a separate repo for drafts management, so we can version control drafts as well without polluting this repo's commit history. This repository would continue to serve for publishing accepted RFCs and maintaining the source of the rfc.tildeverse.org website. The drafts repo would be added as a git submodule to this repository's content/drafts folder. This way, a draft RFC could be submitted as a PR on the drafts repo. Accepting the PR would be the moderation process for drafts. Contribution by other individuals could take place: - before moderation on the source of the PR (eg. southerntofu/drafts, potentially on a specific branch) - after initial moderation on the tildeverse/drafts repo So all discussions about future RFCs would as some point take place on the drafts repo. Following the drafts repo would therefore keep tilde members up to date on proposed standards for the tildeverse. So the contribution pipeline for an RFC would look like this: 1. Fork this repository 2. Create a new branch for the RFC on the fork repo 3. Commit your Markdown file 4. Open a pull request on this repository 5. Initial review takes place (to fend off spammers/trolls) 1. Reviewers propose changes on the PR discussion. 2. External contributors propose changes as issues/PRs on the fork 6. Reviewers merge the PR; draft gets rendered on the website 7. People link to the RFC draft, have discussions, propose changes on tildeverse/drafts in the form of issues/PRs 8. When contributors feel like their proposal is ready for final review, they open a PR on this repository, assigning it the next-available RFC number 9. Final review takes place 1. additional patches can be merged on the drafts repo to keep the public draft page updated 10. When the proposal is finally ready, it is merged by reviewers ## Dependency graph Some semantics should allow to express that an RFC depends on another. More precisely, that implementing an RFC cannot be achieved without implementing those other "required" RFCs. For example, consider a Tor RFC and a webmention RFC. Implementing a webmention over Tor RFC would require implementing the Tor RFC and the webmention RFC. Concretely, this allows to present in a human-friendly manner information about required steps before implementing an RFC. ## Implementation status code We could define an implementation status code for RFCs. We assume here that we have some form of optional "Recommendations" section defined in the RFC format, where every sub-item is an individual recommendation that persons implementing the RFC MAY implement if they wish. To compute the status code, we consider a sequence of bits. Where n is the number of recommendations (second-level headings contained within the Recommendations first-level heading), our sequence contains n bits all initialized to 0. For each recommendation, if it is implemented by the tilde server, the corresponding bit is set to 1. The binary number is then turned to a decimal representation which is the implementation status code for example for a RFC with two recommendations. Here's the list of possible combinations: - none implemented -> 00 -> 0 - implemented 1 -> 10 -> 2 - implemented 2 -> 01 -> 1 - implemented 1 & 2 -> 11 -> 3 Note: this works because the number of recommendations does not change over time. RFC is not edited, but replaced by another RFC. This would allow tilde operators (and other people) to semantically and visually present information about the server's capabilities in regards to tildeverse standards. For example, tildeverse.org could (for the sake of argument) maintain a list of pratchett-friendly servers supporting RFC1.
Author

Some more thoughts.

semantics for status code and implementation report is unenforceable like i proposed it because "implementation" for recommendations cannot always be measured in a binary fashion.

we have to maintain a more explicit set of binary tests for compliance. some sort of doctests-like system would allow us to write those tests as valid computer programs directly within the specification itself.

this leads us down the path to self-enforcing specifications :D
just download the RFC's source, and as you read it you can run tests against your tilde server.

EDIT: also some RFCs cannot be implemented and this should be machine-understandable. Guidelines such as the RFC for making RFCs cannot be implemented by tilde servers. Explicit specifications like supporting Clacks headers or Tor are somehow a different kind of RFC.

EDIT2: two good examples of RFCs simple to implement (in order to test the implementation status/automated testing) would be Clacks and HTTP 418 (i'm a teapot) from the HTCPCP april fool's RFC

Some more thoughts. semantics for status code and implementation report is unenforceable like i proposed it because "implementation" for recommendations cannot always be measured in a binary fashion. we have to maintain a more explicit set of binary tests for compliance. some sort of doctests-like system would allow us to write those tests as valid computer programs directly within the specification itself. this leads us down the path to self-enforcing specifications :D just download the RFC's source, and as you read it you can run tests against your tilde server. EDIT: also some RFCs cannot be implemented and this should be machine-understandable. Guidelines such as the RFC for making RFCs cannot be implemented by tilde servers. Explicit specifications like supporting Clacks headers or Tor are somehow a different kind of RFC. EDIT2: two good examples of RFCs simple to implement (in order to test the implementation status/automated testing) would be Clacks and HTTP 418 (i'm a teapot) from the [HTCPCP](https://en.wikipedia.org/wiki/Hyper_Text_Coffee_Pot_Control_Protocol) april fool's RFC
Author

Maybe the future RFC for RFCs should make it clear what "RFC" refers to:

  • IETF RFC means internet-wide RFC, published by the IETF
  • ~RFC of tildeRFC means tildeverse-wide RFC, published on rfc.tildeverse.org
  • RFC can mean either, depending on the context

An alternative way to avoid collisions and ambiguity could be to find a more specific acronym, like XMPP Extension Protocols (XEPs), Yunohost Enhancement Proposals (YEPs).

Maybe the future RFC for RFCs should make it clear what "RFC" refers to: - `IETF RFC` means internet-wide RFC, published by the IETF - `~RFC` of `tildeRFC` means tildeverse-wide RFC, published on rfc.tildeverse.org - `RFC` can mean either, depending on the context An alternative way to avoid collisions and ambiguity could be to find a more specific acronym, like XMPP Extension Protocols ([XEPs](https://xmpp.org/extensions/)), Yunohost Enhancement Proposals ([YEPs](https://yunohost.org/#/packaging_apps_guidelines)).
Sign in to join this conversation.
No Label
No Milestone
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: tildeverse/rfcs#10
No description provided.