From 002843048bd4515d03f403042f14394b66cd2132 Mon Sep 17 00:00:00 2001 From: Alec Thomas Date: Sun, 14 Apr 2024 20:31:32 +1000 Subject: [PATCH] docs: document design process --- CONTRIBUTING.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9263eb635d..7d061aacdc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,13 +40,30 @@ hot-reloading ftl agent: $ ftl dev ./examples/go ``` -## Development workflow +## Development processes -Because we're a widely distributed team, we use a review-after-merge development flow. That is, if a PR is urgent, minor, or the developer has high confidence, we encourage merging without waiting for review in order to decrease friction. Conversely, if a change is more complex, or needs more eyes, we encourage developers to wait for review if it will make them feel more comfortable. Use your best judgement. +### Code reviews -We discourage bike-shedding. Code and documentation is easy to change, we can always adjust it later. +Because we're a geographically distributed team, we use a review-after-merge development flow. That is, if a PR is urgent, minor, or the developer has high confidence, we encourage merging without waiting for review in order to decrease friction. Conversely, if a change is more complex, or needs more eyes, we encourage developers to wait for review if it will make them feel more comfortable. Use your best judgement. -## Best practices +We discourage bike-shedding. Code and documentation are easy to change, we can always adjust it later. + +### Design process + +Many changes are relatively straightforward and don't require a design, but more complex changes should be covered by a design document. Once a DRI (Directly Responsible Individual, a Cash term) is selected, our process for creating and reviewing designs is the following. The DRI: + +1. Does some initial thinking and comes up with a rough approach. +2. Schedules a short (30-60 minute) design session with the rest of the team to do a basic check that the idea is sane, and pick up any obvious issues. + - Not everyone needs to attend, but those who can should. + - Focus on the larger points, minor issues will naturally fall out during implementation. + - Avoid bikeshedding. +3. Writes the design doc. +4. Send the doc to the team for async review via HackMD comments. +5. Wait for @alecthomas to approve, then implement! + +Our design docs are [stored in HackMD](https://hackmd.io/team/ftl). There's a template for design docs that should be used. Add a label to your design document, representing its state. + +## Coding best practices ### Optional