From f9eb0c612ff028632e4fa1db9008f62215337006 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Mon, 14 Sep 2026 17:22:03 +0300 Subject: [PATCH 1/5] add best practices for sandboxes --- docs/build/sandboxes.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/build/sandboxes.md b/docs/build/sandboxes.md index a3e46331a0e..a752dfcdb92 100644 --- a/docs/build/sandboxes.md +++ b/docs/build/sandboxes.md @@ -279,3 +279,36 @@ If you're working with several sandboxes in one workspace, two things help: the parent project or each other. - `openfn project checkout ` 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. + +**Connect each sandbox to its own GitHub branch.** If you use +[GitHub Sync](/documentation/link-to-GitHub), don't point a sandbox at your +repo's default branch. Create a feature branch for the work and sync the sandbox +to that branch instead. With the v2 sync format you need one two-way sync per +branch anyway, because every project synced to a branch shares the same +`workflows` folder. + +**Open pull requests from the feature branch into main.** Reviewers then see +only the changes that came out of that sandbox. Syncing straight into your main +branch produces one large diff with everything mixed together, which is hard to +review and hard to unpick later. + +**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 +(default 5). 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. From de3a86e4d14b650214c46bcc9e670d5a3812af46 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Mon, 14 Sep 2026 17:31:33 +0300 Subject: [PATCH 2/5] update pull requestion section --- docs/build/sandboxes.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/build/sandboxes.md b/docs/build/sandboxes.md index a752dfcdb92..69ab0516a8f 100644 --- a/docs/build/sandboxes.md +++ b/docs/build/sandboxes.md @@ -297,10 +297,15 @@ to that branch instead. With the v2 sync format you need one two-way sync per branch anyway, because every project synced to a branch shares the same `workflows` folder. -**Open pull requests from the feature branch into main.** Reviewers then see -only the changes that came out of that sandbox. Syncing straight into your main -branch produces one large diff with everything mixed together, which is hard to -review and hard to unpick later. +**Open a pull request for review, but don't merge it into main.** Comparing the +sandbox's branch against your main branch is the easiest way to see what changed +and to leave comments on specific steps. Don't merge that pull request, though: +the branch holds the sandbox's whole project state, including sandbox-specific +configuration that isn't meant to reach the main project, so merging it brings +across far more than the change under review. Promote the change with the +**Merge** action on the sandbox instead (see +[Merging sandboxes](#merging-sandboxes)); the parent project's own GitHub Sync +then commits the result to its branch. **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 From 7106e84da3617e0ea201165d923111abac99262a Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Mon, 14 Sep 2026 17:34:15 +0300 Subject: [PATCH 3/5] drop default value --- docs/build/sandboxes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/build/sandboxes.md b/docs/build/sandboxes.md index 69ab0516a8f..00ce55e096d 100644 --- a/docs/build/sandboxes.md +++ b/docs/build/sandboxes.md @@ -310,9 +310,9 @@ then commits the result to its branch. **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 -(default 5). Do the same in git: branch the dependent work off the feature -branch rather than off main. +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. From 9a892877c8e0613250b7ec29a938d3be671eed96 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Tue, 15 Sep 2026 16:04:15 +0300 Subject: [PATCH 4/5] remove pull request instructions --- docs/build/sandboxes.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/build/sandboxes.md b/docs/build/sandboxes.md index 00ce55e096d..ccaef6dd797 100644 --- a/docs/build/sandboxes.md +++ b/docs/build/sandboxes.md @@ -297,16 +297,6 @@ to that branch instead. With the v2 sync format you need one two-way sync per branch anyway, because every project synced to a branch shares the same `workflows` folder. -**Open a pull request for review, but don't merge it into main.** Comparing the -sandbox's branch against your main branch is the easiest way to see what changed -and to leave comments on specific steps. Don't merge that pull request, though: -the branch holds the sandbox's whole project state, including sandbox-specific -configuration that isn't meant to reach the main project, so merging it brings -across far more than the change under review. Promote the change with the -**Merge** action on the sandbox instead (see -[Merging sandboxes](#merging-sandboxes)); the parent project's own GitHub Sync -then commits the result to its branch. - **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 From 099601b6401a4c83bb948247aebc8b190184090b Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Wed, 16 Sep 2026 12:21:45 +0300 Subject: [PATCH 5/5] remove connect to github --- docs/build/sandboxes.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/build/sandboxes.md b/docs/build/sandboxes.md index ccaef6dd797..436fe8aade1 100644 --- a/docs/build/sandboxes.md +++ b/docs/build/sandboxes.md @@ -290,13 +290,6 @@ 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. -**Connect each sandbox to its own GitHub branch.** If you use -[GitHub Sync](/documentation/link-to-GitHub), don't point a sandbox at your -repo's default branch. Create a feature branch for the work and sync the sandbox -to that branch instead. With the v2 sync format you need one two-way sync per -branch anyway, because every project synced to a branch shares the same -`workflows` folder. - **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