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.
This commit is contained in:
Philip Metzger
2026-05-10 17:48:31 +02:00
committed by Philip Metzger
parent bf15825fe9
commit 3a0dae3df6
2 changed files with 24 additions and 5 deletions

View File

@@ -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

View File

@@ -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