ok/jj
1
0
Fork 0
forked from mirrors/jj

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.
This commit is contained in:
Philip Metzger 2024-06-17 22:17:16 +02:00 committed by Philip Metzger
parent 3792f4a019
commit c4777e4721
3 changed files with 29 additions and 0 deletions

View file

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

22
docs/design_docs.md Normal file
View file

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

View file

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