Skip to content

Commit

Permalink
docs: Formalize our design docs process a bit.
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
PhilipMetzger committed Jun 27, 2024
1 parent 5abc87f commit 0ea2d4d
Show file tree
Hide file tree
Showing 3 changed files with 29 additions and 0 deletions.
6 changes: 6 additions & 0 deletions docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
22 changes: 22 additions & 0 deletions docs/design_docs.md
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down

0 comments on commit 0ea2d4d

Please sign in to comment.