diff --git a/docs/contributing.md b/docs/contributing.md index 18644aa63..76f7ccb7d 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 + +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 diff --git a/docs/design_docs.md b/docs/design_docs.md new file mode 100644 index 000000000..a73e1f210 --- /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 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 diff --git a/mkdocs.yml b/mkdocs.yml index d53162cb4..dfba94a1e 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'