Skip to content

Commit

Permalink
docs: document design process
Browse files Browse the repository at this point in the history
  • Loading branch information
alecthomas committed Apr 14, 2024
1 parent 97b8117 commit 35c5ad2
Showing 1 changed file with 20 additions and 3 deletions.
23 changes: 20 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

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.

We discourage bike-shedding. Code and documentation is easy to change, we can always adjust it later.

## Best practices
### 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

Expand Down

0 comments on commit 35c5ad2

Please sign in to comment.