The RFC RFC

the-RFC-RFC.md

The RFC RFC

There are many kinds of useful artifacts outside of code. This is a discussion of several kinds of docs, how we want to develop them, and how we like to merge and manage them.

Kinds of documents

• Experience Reports
  • If you've just got something to get off your chest, do it in an experience report.
  • Experience reports are meant to be just that: a report. The intent is that the report can have a single author, and as long as it's reasonably interesting, we can merge this -- without needing to reach for solutions, which opens the floor for more debate. Reports should be quick.
  • Example from other projects: https://github.com/golang/go/wiki/ExperienceReports
• Design Docs
  • Design Docs are for synthesizing concerns and proposing (multiple!) solutions.
  • Design Docs often can refer to prior Experience Reports to explain what they're solving.
  • We have some more suggestions about these below.
• Specs
  • Specs can follow from a Design Doc which has reached conclusions.
  • Specs can just say what's true, and link to design docs for explanations rather than re-hashing the explanations inline in the spec.
  • Specs aren't always necessary; sometimes a design doc is meaningful enough already. Specs are particularly useful externally-facing systems and APIs, since other communities then often want to refer to a brief and focused description of the system.

Writing good Design Docs

• A good Design Doc needs to have several kinds of info:
  • All these headers should be present:
    • Overview (what this is about trying to do)
    • Background (optional)
    • Needs (the driving goals)
    • Factors to consider (things that constrain us)
    • Current Situation/Solution (review)
    • Proposals (multiple; rated against the needs and factors)
    • Resolution (maybe! "still looking for alternate proposals", or later "tabled" is also fine.)
  • Great examples of greatness:
    • https://github.com/ipfs/community/blob/master/decisions/community-forum-platform.md
  • Antipatterns:
    • You are not allowed to submit an RFC with only one proposed solution considered. This is absurd. Try harder. If you've only considered one solution, it's very unlikely to be the best possible.
  • Other notes:
    • Starting a design doc with a "Needs" section only, and then filling in the "Factors" iteratively in future PRs can be a great approach! This works especially well if using e.g. small benchmarks to discover real-world design constraints.

Workflows

Different kinds of documents and different kinds of folks might prefer different workflows, and we don't want to be overly prescriptive about how to get things done. However, we do want to focus on getting things done -- and for us, that often means "merged".

So:

• Experience Reports, Design Docs, and Specs should all take the form of files and be versioned and go through a pull request.
  • Github issues are fine for starting discussions, but they're often not suitable for reaching clear conclusions.
• We want things to Merge.
  • If anything turns out too contentious to merge:
    • Break it down into smaller PRs. This might help.
    • If you were writing a spec, maybe you should back up, and this needs a design doc phase first. Design docs leave more room for discussion before conclusion.
    • If you were writing a design doc, maybe you should back up, and this is just an experience report. Experience reports are just a story, not a conclusion.
    • Hopefully now this is uncontentious enough to merge! But if not, consider git merge -s ours to drop the topic, but keep the history.
  • Antipatterns:
    • Branches-on-branches should be avoided if possible. Prefer to make a file named draft-foobar.md on master, and merge incrementally to that; or have a "status=DRAFT" warning in the header of the file.
      • Branches-on-branches become increasingly hard to reason about, discover, and compare; and especially hard to rebase and keep up-to-date with other concurrent changes on the master branch in any sane manner; none of these are desirable.

TODO hash out repo situation. Currently we have 'ipfs/ipfs', 'notes', 'specs', 'rfcs', 'community', 'pm', and probably more. Map this.

The last point about merging drafts seems notable and worth discussing in more detail.

👍 I'm not actually sure what more to say about it, but yeah, that's one of the more important things I want to nail. Branches-on-branches get super unwieldy super fast. Avoiding that and having quick turnarounds on smaller merges is critical to making progress.

The problem I see with the proposed process here is that it still greatly favors inaction over action and continues to put too large a burden on the actors in favor of action.

The current process I would describe as "informal pure consensus." This process puts the largest burden possible on someone trying to do something. Anyone can object, they don't have convince their peers of the objection, and it's on the people in favor of the change to convince anyone objecting. It's basically a veto by any participant and because of the informal nature the objections don't even need to be formalized, they can just be vague dislike of the particular approach.

RFC processes are often more risk averse than code contributions because they are more permanent. But I don't think this is as true for the IPFS ecosystem of RFC's as it is for traditional specifications and languages. Several approaches have already been abandoned in favor of other approaches. The layering and separation of concerns in the stack allows us to swap out one approach for another quite easily. This doesn't need to be modeled on the PIP process, or similar processes in platforms, because these approaches don't have to be supported indefinitely.

If the purpose of the RFC process is simply to agree on an approach before implementation then we should create a process that is much more in favor of action.

I'd recommend something along these lines:

• Define a set of final decision makers for unblocking any RFC change, something like a "Technical Committee."
• When a new change comes in it should default to landing if there are no objections within a set timeframe (72 hours).
  • Once objections are cleared it lands.
  • If there are objections that cannot be resolved it is escalated.
  • This when it lands in WG call and the Technical Committee weighs in. If they can't agree then a majority wins vote is called.

This would clear the issues of every participant having a veto. If someone isn't interested in pursuing their objection and convincing their peers the objection will be cleared.

There may need to be further iterations on this process but it's a good outline that pushes things forward on a reasonable timeframe and unblocks people rather quickly. There's a lot of details missing, like who owns the escalation, how often the TC meets to unblock things, and how formalized objections need to be, but this sort of shows the difference in an approach that tries to relieve the burden of authors and other people trying to get stuff done.

I'm definitely in favor of additional ways to cause a lean towards action, but kind of want to explore that in a separate document.

Previous pushes at an RFC RFC have become simply so long that people stop reading them halfway through. This gist is already probably long enough to be pushing the limit. I'd be all for adding more suggestions about unblocking patterns, possibly culminating in that kind of committee, etc, but probably as a loose link somewhere in this document that says "what to do if things Continue to get Stuck".

This doc is supposed to be just kind of a "hey, write things, yo" nudge. (It's possible calling it "the RFC RFC" is misleading, because "RFCs" are more the "Spec" thing -- the third and most contendable, blockable, tricky, careful thing -- and half the point this doc is trying to express is "for the love of $DEITY, please start writing BEFORE getting to the Spec level, because it's still useful".)

On further thought, really probably the "types of (valid!) work" heading is probably the main thing, and the other two headings, including the whole workflows and please-get-to-merge things are already probably best shipped as separate documents.

(I'd also like to grow the "types of (valid!) work" list to include other things like "benchmarks!", for example.)