diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 298dbae30f..92f9cd84c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,13 +40,32 @@ 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. Once approved by @alecthomas, implement! + +Of course, feel free to bounce ideas off anyone on the team at any time. + +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