Skip to content

Commit

Permalink
docs: document design process (#1255)
Browse files Browse the repository at this point in the history
  • Loading branch information
alecthomas authored Apr 14, 2024
1 parent b32c979 commit 2bd6448
Showing 1 changed file with 23 additions and 4 deletions.
27 changes: 23 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit 2bd6448

Please sign in to comment.