coder --version: Coder v0.5.4-devel+d847d2b

Our CLI and API useimperative language, but what's happening under the hood isdeclarative due to the way Terraform works. A build can have a "transition" set to "start". "Transition" implies that we are changing from one state to another, and "start" is a verb. Then we call Terraform, and if the workspace is already up in the correct state, it does nothing, so we haven't started anything and there was no transition. You can have 10 builds in a row withtransition: start, which doesn't make sense in the usual meanings of those words.

Instead, I think we should adopt adeclarative style language on our API, and replace start/stop with up/down (I'd also be willing to be talked into on/off). Instead of "transition", we should prefer "state" or similar.

I had a conversation with@ketang about this, and I'll try to summarize what we discussed, but invite him to extend, elaborate, or claim that I'm misrepresenting his views in the comments.

Ketan is concerned about our CLI and API adhering too strictly to a Terraform view of the world such that it might make it difficult to build/support additional provisioning systems in future. With this I agree, but we do have to decide one way or another whether our CLI/API is declarative or imperative with respect to workspaces. If our API is declarative, it is easy to imagine how we would integrate with an imperative style provisioner: query the current state, compute the difference, issue commands to bring the actual state to the desired state. The other way around is harder: if you have an imperative API and a declarative provisioner, the input the provisioner wants is the final state, which is hard to compute just from the imperative command.

Secondly, Ketan thinks that verbs are easier to understand. There is some truth to this, but in a declarative API there is really only one verb: reconcile/apply/make. Our DB schema, API, and CLI use "build" which is a verb in common English (although it is used often as a noun in the software world). "Build" would be an unfortunate verb to use because it is counterintuitive to "build" something to the "down" or "deleted" state.

@kylecarbs@ketang@tjcran for discussion.