1601349 - RFC 0 - Use RFCs and determine how/where they should be hosted

Status: NEW

(Conduit :: General, task)

Description

[Israel Madueme [:imadueme]]

This RFC is for us to discuss how/where to use RFCs or ADRs.

Comment 1

[Israel Madueme [:imadueme]]

Mitch can you start us off with a proposal?

Comment 2

[Mitchell Hentges [:mhentges] 🦀]

Proposal:

TL;DR: See the Releng system

We should have an RFC mechanism that will allow the team to collaborate on significant decisions, which can range from team workflow modifications to core architecture changes in our software.
IMHO, we should use the Releng RFC system to influence our solution. Importantly, we should ensure that our system allows communication across time zones and has each discussion exist over a long enough life cycle to ensure that we have considered each potential edge.

I don't have preference for how this is implemented. I'd lean towards Github due to its built-in markdown rendering without requiring a separate site (gif attached).

Comment 3

[Mitchell Hentges [:mhentges] 🦀]

Attachment: RFC-github.webm

Comment 4

[Connor Sheehan [:sheehan]]

(In reply to Mitchell Hentges [:mhentges] from comment #2)

Proposal:

TL;DR: See the Releng system

We should have an RFC mechanism that will allow the team to collaborate on significant decisions, which can range from team workflow modifications to core architecture changes in our software.
IMHO, we should use the Releng RFC system to influence our solution. Importantly, we should ensure that our system allows communication across time zones and has each discussion exist over a long enough life cycle to ensure that we have considered each potential edge.

I don't have preference for how this is implemented. I'd lean towards Github due to its built-in markdown rendering without requiring a separate site (gif attached).

The RFC system seems like a decent idea - I can see the value in providing a template for early feedback on mid-to-large scale projects that may involve stakeholders in different timezones.

On the other hand I don't think any of our requirements facilitate implementing this anywhere but Bugzilla. The requirements I can see listed are "our system allows communication across time zones", "each discussion exist over a long enough life cycle" and "built-in markdown rendering without requiring a separate site" - all of which are provided by Bugzilla. We could create a new Bugzilla component like Conduit :: RFCs, load a default template when filing new bugs in this component, and have everyone on the team make sure they're watching it. Implementing this on Bugzilla would also allow us to file bugs that reference the RFC directly once the work has been planned.

Comment 5

[Mitchell Hentges [:mhentges] 🦀]

One downside of using Bugzilla for this is that it doesn't allow inline comments - it can be beneficial to have threaded discussions about individual points on the RFC. If we just have a linear chain of comments (as we'd need to have in Bugzilla), it'll be hard to track different topics and know when they're resolved

Comment 6

[Zeid [:zeid]]

This was mentioned during the initial discussion, but there can be an advantage to having the finalized RFCs rendered/built, and served in a separate format (e.g. using Sphinx or Jekyll). If we go with Github Pages, as Emma mentioned, that can be done with relative ease.

Some advantages to having RFCs available in this way:

• Easy to navigate interface (i.e. have a table of contents and a search box to search RFCs) vs. having to navigate through a file hierarchy
• After a pull request is merged, revision control will have served its purpose and the final document is what is of most significance. If someone needs to view the commit history or comments on a particular pull request, they still have the option to do so.

Some disadvantages to having RFCs available in this way:

• There will now be two ways of viewing RFCs -- directly on Github, or on the Jekyll site, which may be confusing

Some general advantages of having this RFC system in my opinion:

• New contributors will have easy access to historical decisions that were made via the static site
• New contributors will have a resource that provides architectural decisions for ongoing projects (e.g. projects they may have to be onboarded to)

Comment 7

[Mitchell Hentges [:mhentges] 🦀]

I'm on board with having a rendered site for our RFCs, especially since that gives us some extra flexibility regarding features (such as making RFCs searchable, as Zeid mentioned).

If we do that, we'll need to build a static site and have a pipeline for rendering our (markdown?) RFCs to it. There's an up-front time investment here.

Secondly, even if we put the RFCs on a separate rendered site, we'll still be performing the RFC discussion itself on Github to take advantage of threaded, contextual discussion, right?

If so, perhaps we should do this in two steps:

1. Start a baseline RFC process on Github, using its technical-user-oriented UI to discuss new RFCs and view existing RFCs
2. Get a consensus on where we'd want to host the RFCs, and what kind of features we'd find useful in this site.

Comment 8

[Mitchell Hentges [:mhentges] 🦀]

Discussed a bit in-person at All Hands Berlin. We agreed:

• We'll probably start with an RFC process similar to Release Engineering (leaning on Github for review)
• Hosting a separate site that matches our workflow will be a welcome replacement to Github in the future, but we should wait until we're sure that the improvements will be worth the cost of setting up and maintaining it.
• Kim will create a Github repository to host the RFCs
  • Once done, I'll fill in the repo with usage documentation and the existing RFCs that are currently on BZ

Comment 9

[Emma Humphries ☕️🎸🧞‍♀️✨ (she/they) [:emceeaich] (Pacific Time) use needinfo]

I can offer to get it shaped up to work with Jekyl so we can deploy it on GitHub pages.