Intro #

RFC Hub is a website for keeping track of all of your team's technical proposals in one location (some call these TDD / Technical Design Docs, here we'll refer to them as RFC / Request For Comments). While alternative tools work great for generically editing text and leaving behind comments they often leave something to be desired when it comes to managing the life-cycle and approval process of RFCs.

Consider a Google Doc representing an RFC in your company. Perhaps you add a table at the top with reviewers and tag people with the @ symbol and add a column where they can type APPROVED or REJECTED. While this is great for knowing the status while you're in the RFC, such a table overall lacks semantics and is hard to discover this information externally.

RFC Hub is a tool designed specifically for editing software engineering RFCs and with it comes some niceties that traditional document editing tools lack:

• Edit content using GitHub-flavored Markdown
• Semantically specify which teammates are viewers, optional reviewers, or required reviewers
• Prevent publishing of an RFC unless all required reviewers have accepted or abstained
• Semantically specify which comments are nits vs blocking
• Prevent publishing of an RFC unless all blocking comments have been addressed
• Prevent a published RFC from being modified (e.g. after one begins implementation)
• Revert RFC approvals once the content changes

Features #

RFC Hub is still under active development and the screenshots in this section will change over time.

Markdown #

The usual Markdown suspects are all present. Bold, italic, inline code, strike through, bullet lists, numeric lists, links, image embedding (images are hosted on a CDN built into RFC Hub), code blocks with syntax highlighting, block quotes, tables, etc.

Some things you might not expect are also present, such as mermaid diagrams and GitHub-style alerts.

RFC Status #

The status of an RFC is one of the most exciting features of RFC Hub. In order to change the status of an RFC there is different criteria that needs to be met.

First, consider a large RFC that you've worked on, perhaps managed by Google Docs. There may be hundreds of comments attached to the document, some containing questions, some with nitpicks or ideas, and others that are blocking. How do you know if you've addressed everything when it's time to publish? Dismissing all of the comments helps visually unclutter the RFC but this is often important historical context that shouldn't be lost.

With RFC Hub there is basic criteria required to publish an RFC. Notably, any reviewers who are marked as required must have either approved or abstained from the review process. Also, anyone who has left an important comment on the RFC must have their comment resolved. Without this criteria being met the RFC can't be published.

This set of requirements is similar to GitHub repositories where an organization will often make it a requirement that certain individuals review a pull request before it can be merged.

RFC Visibility #

An RFC can either be Public, Internal, or Private.

• Public: These can be seen by the whole world
• Internal: These can be seen by anyone in the same org that owns the RFC
• Private: These can only be seen by watchers, reviewers, and the RFC owner

Reviewers #

As mentioned above, reviewers can either be marked as required or optional. Reviewers can change their status from awaiting, to rejected, to commented, to approved, or even to abstained.

The statuses loosely have the following meanings:

• Awaiting: The reviewer has been assigned but hasn't left a comment yet.
• Commented: The reviewer has left at least one comment and therefor their review is underway.
• Approved: The reviewer has approved the RFC in its current form.
• Rejected: The reviewer does not approve the RFC in its current form.
• Abstained: The reviewer has chosen not to accept or reject the RFC.

Comments #

Anyone in an org, who has access to the RFC, can leave a comment on it. Comments can either be optional/nitpicks or important/blocking. Comments can also be dismissed. Once dismissed they're still visible but will be de-emphasised.

Comments are currently attached to a "block" of content, for example a paragraph or a code block. In the future we'll allow comments to more granularly affect a given selection of text.

Watchers #

Watchers are useful for when someone is interested in an RFC but doesn't need to be a reviewer.

When someone is watching an RFC they will receive notifications when the RFC is updated. If an RFC is marked as Private then watching allows the person to have access to the RFC.

Links #

Links are ways to semantically associate two RFCs with each other. For example, if an RFC has been marked as deprecated, then you can create a link to the newer RFC which has deprecated the older RFC.

If an RFC is public, and the viewer of the RFC is not in the organization, then only other public RFC which are linked to it will be visible to the viewer.

Links are bi-directional and can be of the following types:

type	outward	inward
supercede	supercedes	is superceded by
obsolete	obsoletes	is obsoleted by
relate	relates to	relates to
block	blocks	is blocked by
duplicate	duplicates	is duplicated by
depend	depends on	is depended on by

Tags #

Tags are associated with a given organization and then assigned to RFCs instead of being simple free-form text. The goal is for an organization to curate their list of tags and come up with an agreed-upon nomenclature to identify things like system names so that redundant tags aren't created. Consider creating an RFC to define your orgs tagging convention.

A long-term goal of tags is to subscribe to them so that that an individual or a Slack channel will receive notifications when a specified tag is added to an RFC. For example, if an organization has a "Photos Service", then they might create a service-photos tag, and anyone who wants to create another service to communicate with it would tag their RFC in that manner. A Slack administrator might then subscribe to the service-photos tag for their #guild-photo-service channel. This way, when someone makes a "Send an overwhelming amount of traffic to the Photo Service" RFC, members of the Photo Service Guild will be notified that they might be interested in reviewing it.

Note that if a user outside of an org is viewing a public RFC the list of tags won't be clickable links. If the user is in the same org then clicking a tag will display a list of all RFCs with that tag in the given org.

History Log #

Most operations that affect an RFC will both send notifications to watchers of that RFC and also generate a history log entry. The most recent log entries are visible at the bottom of an RFC but each RFC also has a complete history log with all operations. This makes it easy to see what things are changing with an RFC and how recently they changed.