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.
- 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.
- 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:
- 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.
- All these headers should be present:
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 oursto drop the topic, but keep the history.
- Antipatterns:
- Branches-on-branches should be avoided if possible. Prefer to make a file named
draft-foobar.mdon 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.
- Branches-on-branches should be avoided if possible. Prefer to make a file named
- If anything turns out too contentious to merge:
TODO hash out repo situation. Currently we have 'ipfs/ipfs', 'notes', 'specs', 'rfcs', 'community', 'pm', and probably more. Map this.
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".)