Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/build/sandboxes.md
Original file line number Diff line number Diff line change
Expand Up @@ -279,3 +279,24 @@ If you're working with several sandboxes in one workspace, two things help:
the parent project or each other.
- `openfn project checkout <project>` switches the active project in the
workspace. Use it to flip between sandboxes you've already pulled.

## Best practices

Sandboxes map neatly onto git branches, and the workflows that work best treat
them the same way.

**Create one sandbox per piece of work.** Give each new feature, fix, or issue
its own sandbox, rather than sharing one long-lived `testing` sandbox across
several people and several changes. Small, short-lived sandboxes are easier to
review and much less likely to conflict when you merge.

**Stack sandboxes when work depends on earlier work.** If a sandbox has to live
for a while (waiting on a review or a release window, say) and you want to start
something that builds on it, create a sandbox of that sandbox instead of merging
early just to unblock yourself. Sandboxes nest up to the configured depth. Do
the same in git: branch the dependent work off the feature branch rather than
off main.

**Avoid building directly on the main project.** Changes made there are live,
and they turn up in the merge of every other sandbox as a diverged workflow.
Start in a sandbox, then merge back when the change is ready.