From c4777e4721cd722e722b7f77594aaac99d72883a Mon Sep 17 00:00:00 2001
From: Philip Metzger <philipmetzger@bluewin.ch>
Date: Mon, 17 Jun 2024 22:17:16 +0200
Subject: [PATCH] docs: Formalize our design docs process a bit.

This adds the basic outline of _when_ a Design Doc should be written. See the next
commit in the stack for the blueprint.

By adding this we hopefully can prevent unnecessary churn from new and longtime contributors,
when they want to add a major feature or rewrite a core part of Jujutsu. The text is written
as a guideline, not a rule.
---
 docs/contributing.md |  6 ++++++
 docs/design_docs.md  | 22 ++++++++++++++++++++++
 mkdocs.yml           |  1 +
 3 files changed, 29 insertions(+)
 create mode 100644 docs/design_docs.md

diff --git a/docs/contributing.md b/docs/contributing.md
index 18644aa63..76f7ccb7d 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -64,6 +64,12 @@ your company's interests, do feel free to approve it.
 This project follows [Google's Open Source Community
 Guidelines](https://opensource.google/conduct/).
 
+## Contributing large patches
+
+Before sending a PR for a large change which designs/redesigns or reworks an 
+existing component, we require an architecture review from  multiple 
+stakeholders, which we do with [Design Docs](design_docs.md), see the 
+[process here](design_docs.md#process).
 
 ## Contributing to the documentation
 
diff --git a/docs/design_docs.md b/docs/design_docs.md
new file mode 100644
index 000000000..a73e1f210
--- /dev/null
+++ b/docs/design_docs.md
@@ -0,0 +1,22 @@
+# Jujutsu Design Docs
+
+Jujutsu uses Design Docs to drive technical decisions on large projects and it
+is the place to discuss your proposed design or new component. It is a very 
+thorough process, in which the design doc must be approved before PRs for the
+feature will be accepted. It shares some similarities with [Rust RFCs] but 
+mostly addresses _technical_ problems and  gauges the technical and social 
+concerns of all stakeholders.
+
+So if you want to start building the native backend or the server component for
+Jujutsu, you'll need to go through this process. 
+
+## Process
+
+1. Add a new markdown document to `docs/design`, named after your improvement 
+   or project. 
+1. Describe the current state of the world and the things you want to improve.
+1. Wait for the Maintainers and Stakeholders to show up. 
+1. Iterate until everyone accepts the change in normal codereview fashion.
+   
+
+[Rust RFCs]: https://github.com/rust-lang/rfcs 
diff --git a/mkdocs.yml b/mkdocs.yml
index d53162cb4..dfba94a1e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -128,6 +128,7 @@ nav:
 - Contributing:
       - 'Guidelines and "How to...?"': 'contributing.md'
       - 'Code of conduct': 'code-of-conduct.md'
+      - 'Design Docs': 'design_docs.md'
 
 - 'Design docs': 
     - 'git-submodules': 'design/git-submodules.md'