Skip to content

SSBC: Create batch change from CLI

Created by: malomarrec

Problem statement

Users want to interact with server-side Batch Changes through the CLI.

There are two main use cases:

  • Some users prefer a CLI workflow, and/or prefer their IDE to our online editor.
  • Some customers use Batch Changes in a CI workflow, and built a wrapper around the CLI. It's likely they'll want to use server-side batch changes instead of their CI agent (tracking execution is much better, distributing over executors), but they'll still need to trigger it from CI. What their CLI wrapper usually does is: when there's a commit to a spec repository, run src batch preview -f spec.yml on a CI agent, and when it completes return the preview link to the user, and let the user take it over from there.

Proposed workflow

Submit for preview/apply

Introduce a -executor flag, that allows users to submit their batch change to executors instead of running them locally. It accepts the same options as the local CLI.

src batch preview -f spec.yml -remote
src batch apply -f spec.yml -remote

optimistically spits out a link to the execution page:

https://sg.acmecorp.org/users/malo/batch-changes/executions/QmF0Y2hTcGVjOiIyamNTcEV2Y01mZCI=

In the MVP, non-implemented options should return a warning eg. "Caching is not yet available on executors, so --clear-cache has been ignored".

Stretch: even better: optimistically spit out a link that redirects you to the execution page if executing/error, and to the preview page if completed.

View status

Once submitted, the user will have to wait a bit for execution to happen. Either they open the link during execution time, or they open the link after execution has completed, in which case they just want to preview or view the applied batch change.

There should be an easy way to navigate from the execution page to the preview or batch change page to address that use case. We could even consider redirecting the user if the batch change execution has completed successfully.

Alternatives considered

I considered several CLI command options, that I'm going to add here for completeness:

Option 1: Same, but with another flag name. I considered -executor, but it did not sound as good.

Option 2: src batch remote <preview|apply> is a good competitor. I didn't choose it because it's harder to toggle from src batch previews spec.yml to src batch remote previews spec.yml. Other verb to consider: executor.

Option 3: src batch submit -f spec.yml. This one feels weird because we lose the option to preview/apply. Also, why introduce a new verb to do the same thing (with a different compute modality)?