From 0ea2d4dbdb19c3e9098b7b70e4ab96622e5259af Mon Sep 17 00:00:00 2001 From: Philip Metzger 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 18644aa631..d3d11c96de 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 + +While we appreciate that you took the time to design/redesign or rework an +existing component, we cannot accept it as easily as that. As it requires a +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 0000000000..8caa02ed94 --- /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 all concerns must be addressed. 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. It also is good if you're +already familiar with the codebase, to not stall the implementation. + +## 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 d53162cb44..dfba94a1ed 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'