Consider that you are responsible for adding a significant new feature to the product you are developing. You’ve been waiting for this chance, and now everyone will realize what a 10x developer you are! You dive straight into “basement” mode after opening a list of the sexiest new libraries and design patterns you’ve been dying to test out. After a week, you triumphantly come up with your ideal pull request!
However, the team’s senior developer rejects it right away, saying, “Too complex; you should have just used library X and reused Y.” How about that? They obviously don’t see how brilliant your solution is, and before you know it, your PR will have 100 comments, necessitating days of reworking.
What exactly is an RFC, then?
To put it simply, an RFC (Request For Comments) is a document that suggests changing the codebase to address a particular issue. Finding the best solution to an issue as a team before implementation begins is its primary goal. Although the open-source community was the first to embrace RFCs, practically all development organizations now utilize them.
This kind of document is also known by various names in the business, such as SDD (Software Design Document) or TDD (Technical Design Document). We won’t debate the differences between them, as some individuals do.
Fun fact: The Internet Engineering Task Force (IETF), the technical group responsible for many of the key internet technologies and protocols in use today, including TCP/IP, developed RFCs! Not too bad, would you say?
When may I forgo writing the RFC and when should I do so?
Therefore, instead of wasting time writing about something you will ultimately code, just do it? There’s no need for an RFC if you’re working on a bug or a very basic feature where the solution is obvious and doesn’t impact the project structure. Open your IDE and get to work!
However, before typing git checkout -b my-new-feature and heading into that sweet coding zone, you might want to take a step back if you are introducing a completely new concept (e.g., introducing a role-based permission system) or altering the project’s architecture (e.g., adding support for running background jobs).
Having said all of this, it may sometimes be difficult to decide whether or not to draft an RFC. You’ve done something similar previously, you’ve mentally planned things out, and you essentially have no questions. Perhaps it’s a more noticeable characteristic. Here’s a little heuristic I like to use to assist with that: Exists more than one apparent method to put this feature into use? Do we have to choose a new library or service? In most cases, an RFC is not necessary if the response to both of these is “No.” If not, a conversation has to be conducted, and RFC is the appropriate method for doing so.
It seems beneficial. What’s in it for me, though?
We’ve covered how to choose when to write an RFC, but here are some more reasons to do so:
- You’ll get clarity and order your ideas. If you have chosen to draft an RFC, you are faced with an open-ended, non-trivial challenge. Putting your ideas down in writing will allow you to examine them more critically and concisely.
- Compared to if you had just plunged into coding, you will learn more. You’ll allow yourself the room to try out several strategies and often come up with something you hadn’t even considered before.
- The expertise on your team will be crowdsourced. Requests for Comments are meant to get input from your team in order to acquire a comprehensive understanding of the issue you’re trying to solve and to fill in any gaps.
- You’ll deepen the comprehension of the codebase among your team members. Everyone in the team will comprehend what you’re accomplishing and how you ultimately completed it if you work together on your RFC. That means you’ll have much more uninterrupted coding time the next time someone has to touch that section of the code since they won’t have to ask you as many questions.
- PR reviews will go much more easily. Do you recall the scenario at the start of this essay, when your PR was turned down because it was deemed “too complex”? This is because you made a significant modification without first getting approval from the rest of the team, and the reviewer is not aware of the context. You may ensure that this kind of problem never arises again by filing an RFC beforehand.
- You’ve completed half of your paperwork already! To be clear, RFC is not the final documentation; you cannot just refer to it. However, you may probably reuse a lot of the content, including words, diagrams, and photos.
I want to think of a new feature right now simply so I can submit an RFC for it, it sounds so fantastic! Joking aside, completing the RFC first ensures that you know precisely what has to be done and that you won’t have to second-guess your approach or how it will be perceived after you write that PR. This makes the coding portion lot more pleasurable.
Okay, OK, I’m sold! So, what is the process for writing one?
I’m glad you inquired! There are a lot of various forms being utilized, most of them more formal, but I like to keep things simple. Although there isn’t a set format for RFCs written at Wasp, they usually include the following elements:
- Metadata: reviewers, date, title, etc.
- Issue / Objective
- suggested remedy (or many suggestions)
- Overview of implementation
- Remarks or unanswered queries
That is essentially the whole of it! This is the general framework you may work with, however each of them can be further deconstructed and improved.
Now let’s review each of them and see how our Authentication in Wasp example uses them in real life.
Metadata
This one should go without saying: you should keep track of some basic information about your RFCs, such as their status and creation date.
Similar to the PR review process, some templates also explicitly list the reviewers and the status of their “approval” of the RFC. We don’t have this because we’re a small team and communication moves quickly, but it can be useful for larger teams where there are more people and you want to have a little more structure in place (for example, when mentoring junior developers).
The problem
Things start to become intriguing at this point. All of the next phases will be simpler if you can clearly state the issue, the objective, or feature you must create, as well as the reasons behind it. Therefore, it is worthwhile to invest in this even before you begin drafting your RFC; be sure to consult with all relevant stakeholders (such as the product owner, other developers, and even consumers) in order to better understand the problem you will be tackling.
By doing this, you’ll also probably pick up some first cues and suggestions about potential solutions and get a general understanding of the issue domain you’re in.
From the given example, the following are some pointers:
- Provide a high-level synopsis at the outset so that readers may determine right away whether or not this is relevant to them and whether or not to continue reading.
- Give some background information: Give a brief explanation of the present situation in the globe. Depending on who the target audience is, this might be one line or a whole chapter.
- Give a detailed explanation of the issue and its purpose, tying it to the suffering of the user or business to make the motive obvious.
- If you can, include more information like diagrams, code samples, or anything else that will assist the reader reach that “aha” moment more quickly. Bonus points for using foldable portions, which maintain the RFC’s consumable length in the middle.
You’re already quite close to the great RFC if you completed all of this! As precisely describing the issue is crucial, don’t hesitate to elaborate and further deconstruct the situation.
Not-goals
Under the “Problem” or “Goal” section, this is the subsection that may sometimes be quite beneficial. It might be helpful to clarify the expectations and scope of this codebase change by outlining what we do not want or will not be doing.
People could believe, for instance, that if we are developing an app with role-based authentication, we would also include some kind of admin panel to manage users and add/remove roles. Reviewers will better grasp your objectives if you state clearly that something won’t be completed (and quickly explain why—it’s not required, it would take too long, it will be done in the next iteration, etc.) and you will save needless conversation.
Resolution & Execution
Upon determining our goals, the next step is to choose the most effective approach! Although you may have previously alluded to a potential solution in the Problem section, here is the time to go further. Look at several strategies, weigh their advantages and disadvantages, and make a rough sketch of how they might work with the current setup.
This is perhaps the most flexible portion since there shouldn’t be many limitations applied here because it really depends on the kind of work you are performing. You could need to go deeply into the code and begin developing portions of the code you will require, or you might wish to stick at the upper level of, say, system architecture. Because of this, I have provided you with a set of suggestions rather than a specific framework to follow:
Compose pseudocode
RFC is not meant to be production-grade code that complies with all edge situations; rather, it is meant to communicate concepts and ideas. Feel free to create, envision, or sketch anything you need (for example, suppose you already have an email-sending function; use it, even if you don’t), and don’t burden the reader or yourself with implementation specifics (unless that is specifically the subject of the RFC).
It is preferable to begin at the highest level and work your way down as necessary or at the recommendation of a reviewer.
See how others are achieving it
Depending on the kind of product you’re making, there may be a different way to determine this, but there is nearly always a method. If you’re creating an open-source tool like Wasp, you can easily see other well-liked (also open-source) solutions and take note of how they achieved it. You can probably ask some people who have done it previously if you’re working on a SaaS project and need to decide whether to utilize cookies or JWTs for authentication. Finally, just Google/GPT it.
Why is this so beneficial? The rationale is that it boosts your confidence in your answer, as well as that of the reviewers. It may be a good path if someone else completed it in this manner with success. Additionally, it may open your eyes to previously unconsidered strategies or provide a foundation upon which you may expand. Naturally, you should never take anything for granted and consider the unique requirements of your circumstances, but you should also obviously use the knowledge and experience of others.
Don’t make things flawless and leave them unfinished
The collaborative component of RFC—yes, I am aware that it really stands for “comments”—is what really matters. RFC is not an exam where you have to pass with flying colors and answer all the questions; if that’s the case, you really ought not to have taken the test in the first place.
Problem solving is a collaborative endeavor; you are only the one making the first attempt and driving the process forward. You have to provide as much foundation as you can in order for the reviewers to rapidly understand the situation and offer helpful criticism that is targeted where it is most required. This may be done by refining the issue, considering many ways to solve it, and identifying new subproblems that have emerged.
Your RFC should focus on highlighting the most critical issues and drawing the reviewer’s attention to them rather than trying to remedy them.
Consider the RFC you are creating as a work in progress and a conversation area rather than a finished product that must be polished before being presented to the public.
Notes and unresolved queries
You may emphasize the most important unanswered issues and provide a summary of the primary ideas in this document’s last section. The reader may find it useful to be reminded of the places where his attention may be most beneficial after looking over everything.
Which program ought should I use to draft my RFCs? There are many of options
Although it certainly isn’t the most crucial aspect of RFC-ing, the tool you choose does significant since it establishes the process for it. Naturally, if your organization has already decided on a tool, stay with it. If not, the most popular options I’ve seen are listed below, along with brief remarks:
- Google Docs is the traditional option. Easily able to leave comments on any section of the document—this is the most crucial aspect.
- Notion is an excellent tool for teamwork and provides markdown elements like tables and collapsibles to enhance the readability of your request for proposals.
- GitHub problems and PRs are sometimes utilized, particularly for open-source software projects. The disadvantages include the inability to remark on individual paragraphs of the paper (you can only comment on whole lines) and the awkwardness of incorporating diagrams. One advantage is that all of the code and RFCs remain on the same platform.
Although Notion is what we use now, any of the options above may be a smart pick.
Summary
We’ll provide a summary at the conclusion of this RFC, since that’s great practice as well! I hope you find this essay helpful – it turned out to be longer than I had anticipated, but there were a lot of topics to cover!
The ability to conceive the issue, articulate your ideas effectively, and objectively assess potential solutions while gathering input from the team is what will ultimately enable you to create the ideal product—the ultimate productivity boost. You become a 10x engineer in this way.