introducing rfd, again

I’m a RFD fanboy! I love reading them, and I wish for a workplace which follows them. I’m a 10x engineer if I write an RFD beforehand (even a minimal one for myself). At work, I always find opportunity for applied ideas and writing specifics makes it concrete and relevant given known implicit constraints.

Secondly, getting your team to talk based on a common medium is a winner. Any common medium - RFDs, emails, “a sprint ceremony”. Hey! if it works for you, great! RFD is more productive than meetings and in absence of an existing culture, I push for RFDs (or equivalent) to share technical improvements (features or tech-debt).

Finally, I’m a huge proponent of Boring Tech Club and I strongly believe throwing new-shiny-tech is never an answer to any problem. Having RFDs as an enforced approach cuts half of the water-cooler suggestions. A log of RFDs can quickly show (in metrics) the innovation tokens spent by team and prevent team from investing time and effort into a new thing.

Following is a sanitized 001-rfd-template that I submitted to my monorepo/docs folder seeking comments and commitment from team. This is a reference for myself, and if this is inspiring, adopt below or choose from amazing content on the internet (keyword: ADR/RFD).

Summary

Introducing Requests for Discussion (RFDs) as a lightweight process for proposing and discussing significant decisions for us (TEAM NAME).

An RFD is a numbered document that describes a proposal for a significant change, decision, or initiative. The intention is to have a structured method to document ideas, gather feedback from team members, and reach consensus before implementation. Some alternate goals can be:

• A thinking tool - Writing forces clarity of thought. Most ideas are vague and come to life during implementation. However, overall direction for team is to achieve our OKRs and writing down an idea makes it concrete and tests its alignment with team vision and aspirations
• A discussion artifact - it provides a focal point for feedback. Instead of a decision made in isolation or in absence of historical context, RFDs provide an opportunity for team to transparently share ideas, and gather feedback
• A decision record - it documents what was decided and why. A new joiner can go through previous RFDs and understand our culture, way of working and past choices about architecture, technology and tooling.

There are many successful inspirations in both open source and enterprise settings for RFDs:

• Oxide’s RFDs is a piece of art
• Joyent’s RFDs is another enterprise RFD building their products with RFDs
• Rustlang RFCs in open-source setting drives development of a performant systems language
• PEP or Infamous Python Enhancement Proposal
• SPIP are improvement proposals for Apache Spark

The list of inspirations is endless.

When to Write an RFD

Write an RFD when you’re considering:

• Architecture decisions - New data pipelines, schema changes, technology choices. Few practical examples are:
  • Migrating from monolithic to modular pipelines
  • CI/CD strategy for data platforms
  • Infrastructure-as-code adoption for data workloads
• Process changes - Workflow modifications, team practices, tooling adoption. Few practical examples are:
  • Using RFD for discussions
  • Using monorepos and git to track all code changes
  • Way of working improvements
  • Using precommit hooks
• Standards - Naming conventions, coding patterns, documentation practices. Few practical examples are:
  • Unity Catalog Design
  • Python or SQL Coding standard
  • Using linters for Python and SQL
• Cross-team initiatives - Changes affecting multiple teams or systems. Few practical examples are:
  • Shared data catalog design
  • Cross-team development workflows
  • Data platform governance policies

Don’t write an RFD for:

• Topics that require formal governance approval
• Bug fixes
• Minor refactoring
• Documentation updates
• Changes with obvious solutions and minimal impact

Rule of thumb: If you’d naturally discuss it with the team before implementing, consider an RFD.

RFD Lifecycle

+-------+     +------------+     +----------+
| Draft | --> | Discussion | --> | Accepted |
+-------+     +------------+     +----------+
                    |                  |
                    v                  v
              +-----------+     +------------+
              | Abandoned |     | Superseded |
              +-----------+     +------------+

Who is Involved

Anyone can author an RFD. All team members are encouraged to review and comment.

Process

This section expands on the lifecycle with practical guidance for common scenarios.

Scenario: Drafting a new RFD

• Create a new markdown file: docs/rfd/NNN_short_title.md (no number yet)
• Use the template as a starting point, or structure it your own way. The template below is optional guidance. If you have a clear structure that covers the essence of your proposal, feel free to adapt or skip sections. The goal is clarity, not bureaucracy.
• Set state to Draft in the metadata
• Open a PR to track changes and enable comments

Scenario: Gathering feedback

• Update state to Discussion when ready for feedback
• Share the PR link in the team channel
• Reviewers add comments on the PR or in the document
• If the topic needs deeper conversation, the author can call for a meeting to gather input and work through open questions
• Author addresses feedback by updating the document and pushing changes
• If there is not enough feedback on RFD, we can mention in recurring standup or “accept RFD by omission”.

Scenario: Finalizing an RFD

• When consensus is reached, update state to Accepted
• Assign the next available RFD number and rename the file by replacing NNN in docs/rfd/NNN_short_title.md
• If the proposal is withdrawn or rejected, update state to Abandoned and briefly document why - this is valuable context for future reference
• Merge the PR

Note on RFD numbers: RFD numbers are assigned only when the RFD reaches a final state (Accepted or Abandoned). While in Draft or Discussion, reference your RFD by its PR link. When finalizing, pick the next available number.

Scenario: Superseding an existing RFD

Superseded is a special state for when a new RFD replaces an older one. This happens when requirements evolve significantly or a better approach emerges.

• Draft the new RFD as usual, referencing the old RFD it will replace
• In the new RFD, explain what changed and why the old approach no longer fits
• When the new RFD is accepted:
  • Update the old RFD’s state to Superseded
  • Add a note at the top of the old RFD linking to the replacement: Superseded by RFD NNN
• The old RFD remains in the repository as historical context