🔬 Design documents

The design documents (or "design docs", more commonly) describe potential designs. These docs vary greatly in terms of their readiness to be implemented:

• Early on, they describe a vague idea for a future. Often this takes the shape of capturing constraints on the solution, rather than the solution itself.
• When a feature is getting ready to ship, they can evolve into a full blown RFC (see the procedure to propose an RFC), with links to tracking issues or other notes.

Early stage design docs

In the early stages, design docs are meant to capture interesting bits of "macros design space". They are often updated to capture the results of a fruitful conversation or thread which uncovered contraints or challenges in solving a particular problem. They will capture a combination of the following:

• use cases;
• interesting aspects to the design;
• alternatives;
• interactions with other features.

Late stage design docs

As a design progresses, the doc should get more and more complete, until it becomes something akin to an RFC. Often, at that point, we will expand the design document into a directory, adding an actual RFC draft and other contents; those things can live in this repo or elsewhere. Once we decide to put a design doc onto the roadmap, it will also contain links to tracking issues or other places to track the status.