Writing down ideas is important. It allows them to be more rigorously formulated, even while still nascent, candidly discussed, and transparently shared across Earendil and the world.

At Earendil, we capture the written expression of an idea in a Request for Comments (RFC). In the spirit of the original RFC process, these documents are meant to encourage structuring thoughts, sharing ideas and publishing concepts. An RFC may contain a rough idea, a specific proposal, background and context, open questions, implementation suggestions, or a partially formed direction. The goal is to make ideas easier to discuss, improve, and preserve.

RFCs should be lightweight enough that people feel comfortable writing them early, but durable enough that they become part of our shared company memory. Some RFCs will begin as rough drafts and evolve quickly. Others will document decisions that are already well understood. In all cases, the purpose is the same: to make important ideas visible, discussable, and easier to reason about over time.

Earendil strives to operate on consensus when possible and RFCs are a good mechanism by which this can be accomplished.

When to use an RFC

RFCs are appropriate for a broad range of topics. Examples include:

Sharing ideas and thoughts
Architectural or design decisions for software or systems
Changes to APIs, interfaces, or tools used by customers
Changes to internal APIs, infrastructure, or tooling
Changes to internal workflows or operations
Designs for testing, rollout, migration, or reliability work
Significant product or business decisions that benefit from written discussion

RFCs are not only for technical proposals. They can also be used for company, product, operational, or organizational ideas. If you have an idea that would improve how Earendil works, RFCs are one way to make that idea concrete and invite feedback. Published RFCs are also canon when it comes to what we agreed on at an earlier date.

What to include in an RFC

An RFC should make the problem and the proposed direction understandable to someone who is not already deeply involved. In particular, it is useful to include:

The problem or opportunity being addressed
Relevant background and context
The viable options considered, or at least the most realistic alternatives
The benefits and drawbacks of each option
The reasoning behind the recommendation
The proposed decision or direction
Open questions, risks, or unresolved details
The expected impact on the company, product, systems, or customers

Where possible, RFCs should document not just what we decided, but why. This helps future readers understand the reasoning, revisit assumptions when circumstances change, and avoid re-litigating old decisions without context.

Not every RFC needs the same level of rigor. Some topics are urgent and need a lightweight document. Others are foundational and deserve deeper analysis. Use good judgment in balancing thoroughness with speed.

Public and Private RFCs

Earendil supports both public RFCs and private RFCs.

Public RFCs are intended to be shared externally and published to the world.
Private RFCs are internal-only and visible only within the company.
Additionally you can also mark an RFC as confidential. It works exactly like a private RFC but it just denotes an extra level of confidentiality for anyone who views it.

The author should decide which type of RFC is appropriate based on the content. In general, internal strategy, sensitive technical details, customer-specific information, security details, or confidential operational matters should remain private. Broader product, technical, or company thinking that is appropriate to share externally may be published as a public RFC.

Both public and private RFCs should follow the same basic process and level of clarity.

RFC Discussion

RFCs are written and discussed in Google Docs. Feedback happens directly in the document using comments and suggestions.

This is intentional: discussion should happen as close to the text as possible. Comments allow people to ask questions, challenge assumptions, suggest alternatives, and improve clarity without requiring a separate review system.

Authors are encouraged to actively engage with comments, resolve them when appropriate, and revise the document as the discussion evolves. Reviewers should aim to give constructive, empathetic feedback that helps improve both the proposal and the document itself.

RFC Metadata

At the top of every RFC, include a small amount of metadata so the document is easy to understand and organize. This should include:

Author(s): the owner or owners of the RFC
State: the current stage of the RFC
Visibility: public or private
Created: date first created
Last updated: most recent meaningful revision
Tags: a short list of categories such as product, infrastructure, process, security, customer, operations, etc.
Block Sync: when set to “Block” the RFC publish workflow will not update the published document. This can be helpful when revising already externally published documents.

If useful, the RFC may also include:

Reviewers
Approvers
Target decision date
Related documents or links

RFC States

An RFC can be in one of the following states:

Draft

A document in the Draft state is still being worked on by its author. It may be incomplete, rough, or actively changing. Drafts are often used to gather thoughts and shape the proposal before broader review.

Discussion

A document in the Discussion state is ready for feedback from others. At this point, the RFC should be shared with the relevant audience and comments should be invited directly in the Google Doc.

Published

A document in the Published state has completed its main review cycle and is being retained as an official reference. Published RFCs may still be edited for clarity, corrections, or minor updates.

Accepted

A document in the Accepted state represents a direction or decision that the company has chosen to follow. This means the proposal is no longer just under discussion; it reflects an agreed path forward.

Abandoned

A document in the Abandoned state is no longer being pursued. This may be because the idea was found to be non-viable, superseded by another direction, or no longer relevant. Abandoned RFCs should usually remain available for historical context.

RFC Lifecycle

1. Create a new RFC

To create a new RFC, make a copy of the RFC template and place it in the designated RFC Google Drive folder. Choose whether the RFC should be public or private.

Use a clear title so others can quickly understand the subject.

2. Fill in the initial draft

Start by describing the problem, context, and proposed direction. The initial version does not need to be perfect. It should be complete enough that others can understand what is being proposed and why it matters.

At this stage, the RFC will usually be in the Draft state.

When you are ready for feedback, update the RFC state to In Review and share the document with the appropriate people or groups. Invite comments directly in the Google Doc.

Because there is no separate git or branch workflow, the Google Doc itself is the working space for drafting, review, and revision.

4. Discuss and revise

As feedback comes in, revise the RFC directly in the document. Resolve comments where appropriate, clarify areas of confusion, and incorporate useful suggestions.

The author is responsible for driving the document toward a clearer and better outcome, but discussion should remain collaborative and open.

5. Publish the RFC

Once discussion has converged, the RFC can move to Published. At this point it becomes part of the company’s documented knowledge and can be referenced by others.

If the RFC reflects a direction that has been agreed upon, it may also move to Accepted.

6. Update later if needed

RFCs are living documents. Even after publication, they may be updated to correct mistakes, add clarifications, reflect changed circumstances, or link to follow-up work.

If the proposal is later rejected, replaced, or no longer relevant, the RFC should be marked Abandoned rather than deleted.

Process Changes

This RFC process is itself open to improvement. If we find better ways to draft, review, organize, or publish RFCs at Earendil, we should document and adopt them. The process should serve the company, not the other way around.