From 3a0dae3df604d57fbda03a9bcd5b536c8ae036bb Mon Sep 17 00:00:00 2001 From: Philip Metzger Date: Sun, 10 May 2026 17:48:31 +0200 Subject: [PATCH] docs: Clarify the expectations around design docs a bit more The project at this point has had multiple people show up with Design docs where it was clear that they neither understood the concept of them or just wanted to discuss some idea which clearly belongs into a downstream project. A part of this also discourages them to people which have no experience on the project yet. I personally also would like to discourage genAI usage for writing them, but that seems problematic since the project isn't really clear on their usage, since the goal of them is clearly not to produce 10'000 words but an actual understanding of the problem and approaches to solve it. --- docs/contributing.md | 25 +++++++++++++++++++++---- docs/design_docs.md | 4 +++- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 45dff3055..aaa2b294a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -124,10 +124,27 @@ which there is no final removal date yet. ## 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). +We welcome contributions from anyone. + +If you wish to contribute a new large feature, you are encouraged to discuss +it in Discord or a GitHub Discussion first before diving in. Before spending +too much time on a particular design, you should see if the community and the +maintainers have any feedback on your idea and general approach. It also is a +better experience for you as an author if you contributed smaller patches +first, so you understand how the project and the community around it works. + +If you open a pull request without discussion first, you may find that the +community already has discussed this and found a better approach, or that it +already was deemed not to be a fit for the project. + +Since many ideas have come up before, but they haven't been implemented because +they might be deceptively nuanced, or there may be strong opinions around them, +bringing it up to the community first helps discover past discussions, so your +design can be informed by them. + +Once you have vetted your idea with the community, please write a +[Design Doc](design_docs.md) which requires an architecture review from +multiple stakeholders, see the [process here](design_docs.md#process). ## Contributing to the documentation diff --git a/docs/design_docs.md b/docs/design_docs.md index 5d51aa6ca..7e42af19a 100644 --- a/docs/design_docs.md +++ b/docs/design_docs.md @@ -1,6 +1,6 @@ # Jujutsu Design Docs -Jujutsu uses Design Docs to drive technical decisions on large projects and it +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 @@ -10,6 +10,8 @@ concerns of all stakeholders. So if you want to start building a native backend or the server component for Jujutsu, you'll need to go through this process. +[Design Docs]: https://blog.ceejbot.com/posts/design-docs/ + ## Process 1. Add a new markdown document to `docs/design`, named after your improvement