Requests For Discussion

[afflom]

TL;DR

We are inspired by the IETF RFC process and the RFD process defined by Oxide Computers. We, the UOR Foundation, will adapt the RFD process for our own use and adopt RFDs as our primary method of collaborating on the UOR Foundation vision and mission.

Discussion

There is no such thing as a "good" RFD, but including some features within an RFD increases its effectiveness, if efficacy is to be measured by organizational or technological impact. An effective RFD might include the following elements to prompt others to engage with it:

1. Title - Scopes the discussion in a clear and concise way. It would be ideal for a reader to have a good idea of what the RFD is from its title.

2. Abstract/TL;DR - Provide the tl;ldr to focus the reader on the discussion subject-area.

3. Background - Context that helps a reader understand why the RFD was created.

4. Discussion - Provide a clear and succinct decomposition of the discussion into frames that readers can expand on in the discussion. These frames might address the 5w's. Depending on the discussion, it may be helpful to further frame the 5w's as suggested in Oxide RFD-01; it is ideal to understand the business-case or benefit of the discussed point. This might be typically referred to as a value proposition.

5. Artifacts/links - An RFD will be more accessible to readers if the discussion is presented in a multi-media context. In addition to written; diagrams, pictures, video, audio, and other multi-media formats used to convey a concept are encouraged.

6. Desired outcome: if the RFD is to be transitioned from a discussion to a published decision, what is the specific desired outcome? Being specific here is helpful. Is there a scope of work? Is there a specific ask?

In addition to these fields, we can rely on GitHub for RFD numbering, labels/tags, links to and from issues, and other collaborative/communication features that GitHub provides.

Outcome

By publishing this RFD, we formalize the RFD as the decision record and process for the UOR Foundation. All decisions made by the UOR Foundation will be formalized and published similarly.

The proposed lifecycle for RFDs is:

Proposed: The high-level concept and direction for RFDs are proposed as discussions.
Draft: If the high-level direction for the RFD is clear, we move it to a PR so we can have more low-level feedback and iterate more easily (as we have in-line commenting, etc.). I think this is the state for many of the RFDs that you have opened already. They are really well-defined and scoped and I think we can already move to draft state of iterating at a low-level.
Accepted: Once we are happy with the PR and it becomes part of the repo available for everyone to read.
Final: Once implemented we edit the spec to match the implementation or any additional information that may have been surfaced in the process and mark it as final in a follow-up PR.

In addition to formalizing the RFD process, this RFD also specifies artifacts to be implemented such as PR templates and issue templates.

[adlrocha]

This is perfect! It sets the context and is simple and concrete enough for everyone to be able to start writing their own.

I find this helpful already for myself, as it'll let me organise the ideas with in a clearer form. Thank you for kicking this off!

[adlrocha]

After going through the other more technical RFDs which are really detailed and well-defined I've been thinking about what would be the best process moving forward. Let me know if this sounds good as the de-facto lifecycle for RFDs:

• Proposed: The high-level concept and direction for RFDs are proposed as discussions.
• Draft: If the high-level direction for the RFD is clear, we move it to a PR so we can have more low-level feedback and iterate more easily (as we have in-line commenting, etc.). I think this is the state for many of the RFDs that you have opened already. They are really well-defined and scoped and I think we can already move to draft state of iterating at a low-level.
• Accepted: Once we are happy with the PR and it becomes part of the repo available for everyone to read.
• Final: Once implemented we edit the spec to match the implementation or any additional information that may have been surfaced in the process and mark it as final in a follow-up PR.

If this makes sense to you I would test the process by moving this one to a PR, try to get it merged and I would move to the next ones one-by-one. I think this may help identifying what is the state of each RFDs and track progress more easily. Happy to discuss sync if you feel is easier. Thanks!

[adlrocha]

I would also describe this process into this RFD1 before creating a PR. And maybe we can include a template to help with creating new RFDs

[afflom]

So that I get this right, the journey is:

1. open a discussion post to propose the RFD scope and purpose
2. open PR to hologram repo with a spec once scoped and defined.
3. When merged, Spec PR spawns a linked project/issues
4. Implement the linked project
5. Create a follow-up PR that updates the Spec status and adjusts any implemented details.

This keeps the discussion forum more open for discourse and funnels ideas into defined projects.

Is this consistent with your thoughts?

[afflom]

@adlrocha I updated this discussion from your feedback. Once we hammer this out, I'll create the PR.

[adlrocha]

Yes, that is exactly what I meant ;) We can test the flow with this RFD and iterate if we see it is too cumbersome/painful. We can make this RFD1 and include an RFD template in the repo. Once we get this, we can start moving to the next RFDs you already drafted, WDYT?

The only things I am maybe missing from this RFD is to have a header for RFDs that help us identify them, and so we can add authors, and some additional metadata (example of what we were doing at Filecoin here. But no need to address this in this discussion, we can address that directly on the PR.

(btw, let me know if you want me to open these PRs for you).