RFC Hub
17 points by tlhunter
17 points by tlhunter
Looks awesome! Any plan on opensourcing it? I would really see myself using it with my team but there's no way my company would agree to store this information outside its premises.
I might open source it. Most of the projects that I work on of this magnitude eventually end up open source.
I think there is a certain value to having something like this be centralized. My goal is for it to be like GitHub where one account is used to access technical documents across many organizations with some of the content being public and some being private.
s/RFC/ADR/g and some doc format choices (i.e., the Nygard ADR format) and you'd make the Architecture Decisions Records community super happy, I'll bet. I'm going to share this. This is great.
Thanks for that link! I'll check it out. I did originally plan for every company to be able to configure their own XYZ prefix (there's a vestibule of this that you can see here by replacing rfc with any arbitrary acronym like ADR):
https://rfchub.app/rfchub/ADR1-org-batch-markdown-exporter-job
The overall namespace is the org slug (rfchub in this case) so I was going to allow different orgs to choose the same prefix (defaulting to RFC). In that respect the actual globally unique identifier for this proposal is rfchub/rfc1.
But then I tumbled down the feature creep hole. I'll add templates at some point; maybe the template is then associated with the prefix? E.g. RFC = backend proposal template prefix, GUI = frontend proposal template prefix, etc. I'm hoping to punt on those decisions now until I get more user feedback.
Looks interesting. Curious about:
In my limited experience with RFCs, the hard things have been (1) making sure the right people give them the right amount of attention and (2) proper follow-ups on whether the RFC was implemented or not (and if partly, then what things were skipped).
I've worked as a software engineer at several companies over the past couple decades and a few of them used RFCs. My main gripes are that somebody would change an RFC after it's published, that it's not clear when all of the criteria to publish an RFC have been met, and keeping track of all the RFCs that I care about was difficult. The stack of comments is also an issue, and dismissing a comment in a Google doc feels like a loss of information. I'm hoping to solve all of those issues with RFC Hub.
I haven't seen Liner but I'll check it out, thanks! Finding competing tools has been difficult since it mostly pulls up IETF style RFCs.
RFC Hub also has a notification system so as a reviewer or watcher of an RFC you'll get a notice when the status changes. I'm hoping to integrate with Slack soon to better notify.
One of the best features will be external links to, say, implementation PRs.
I was thinking about something like this recently. I think it would work great if we could just take something like HackMd (collaborative, in Markdown), and add on top Google Docs style viewer/commenter/editor permissions.
In other words, just Google Docs but works in Markdown.
We use Google Docs at work and it actually works really great. My only problem is it doesn't use Markdown.
I don't think commits/changelogs are necessary for every change. For larger changes you can manually maintain a changelog at the end which doesn't take too much effort: just a bulleted list with dates and descriptions, and dates can be inserted automatically with @today or similar.
With the viewer/commenter/editor permissions the people working on it get editor permissions, the public get viewer permissions, and then you can invite specific people for commenting.
My one buddy was pretty adamant that I should have built this backed with git. Admittedly, it would have solved the diffing problem more elegantly, and then you get user permissions for free if it's all on GitHub...
Overall I wanted something with more semantics built in. Storing everything inside of the document makes this pretty hard. The RFC Hub sidebar shows basically all of the metadata which is stored outside of the document. Fun fact, if you click the download button on the right of an ROC, you will get a markdown document with frontmatter yaml containing all the metadata.
Does this have a comment section after the RFC to discuss things?
That's the other thing Google Docs lacks. Comments need to fit into the side notes of a page.
If you have
a long comment
it looks like
this sometimes.
Having a comment section at the end (like in GitHub issues/PRs) would be helpful.
While comments are attached to a specific block of markdown they don't render in the sidebar like Google docs, which was intentional to avoid the weird scrolly Google docs comments situation.
That said, the modal they appear in is rather thin, I'll make it wider on desktop.
I still think Oxide has the slickest RFC interface: https://rfd.shared.oxide.computer/
Those do look pretty nice, thanks for sharing! It looks like they use the moniker "RFD", there are so many conventions for this. It also looks like they have a "group" convention for controlling who can see what. Currently RFC Hub just has private, internal, and public, but groups makes a lot of sense.
For sure. Oxide’s platform is open source for others to host, with the public one only containing their documents. I imagine groups are useful for things like security discussions pre-disclosure, even internally?
Platform aside, their documents themselves are also just nice examples to give as reference to people who haven’t been in an RFC heavy culture.