This could introduce a circular dependency between the two, as template versions require the ID of a template at creation (it cannot be added later), and templates must know the IDs of all template versions associated with it. To fix this, only the template version would point at the template, and not the other way around.
For example:

resource "coderd_template" "debug" {
  name = "debug"
  [....]
  acl = {
     [....]
  }
}
resource "coderd_template_version" "v1" {
  name = data.git_branch.main.sha
  directory = "./dogfood"
  template_id = resource.coderd_template.debug.id
  active = true
}

The Terraform internal logic would then be:

1. Identify the template resource as a dependency of a template version.
2. Create a template resource with no associated version
3. Create a template version resource with the ID of the template resource. During this creation, modify the template on coderd to include the template version ID. If the template version is marked as active, set it as the active version.

This updating of templates from template version resources feels a bit janky, or at least not Terraform idiomatic.

I therefore propose that the schema for creating templates using Terraform should instead look like:

resource "coderd_template" "dogfood" {
  name = "dogfood"
  versions = [
    {
      name      = "dogfood-old"
      directory = "./dogfood-old"
    },
    {
      name      = "dogfood-new"
      directory = "./dogfood"
      active    = true
    }
  ]
}

This means we'd just do the third step in one resource creation task.

In a Netgru meeting, we decided we'd prioritise uploading template versions by having users supply a path to their directory. It's then pretty trivial to just have Terraform compute a hash of all the contents during planning, and use that to determine whether or not the template version needs updating.
However, we can't update the contents of a template version, we can only create a new version.
This means internally, a terraform representation of a template resource would only represent the state of the latest version, and the previously created versions would be effectively 'orphaned', with no way to modify their state on coderd via Terraform, outside of simply deleting the template resource. I don't believe we can avoid this orphaning of versions, though I'm open to suggestions.

This feels like the only surprising part of the schema; that each version in the versions list doesn't actually represent a single version on coderd. In reality, these versions listed in the resource are more like parallel branches of the template, and what's written in Terraform is merely the head of each branch, and where one of those branches can be marked as 'active'.

(We can also just not support multiple template versions through Terraform as in the above snippet, and instead just have a template resource be given a single directory, the implementation is basically the same either way.)

I think this is our best option, but I'm keen to hear thoughts. With this, template creation is still idempotent, and we don't have any circular dependency issues.