Template upgrades

[drevell]

TL;DR

Allow old template output directories to be upgraded when a new template version is released.

Detailed design

(copying portions of an internal design doc)

When the user runs abc templates render to render a template, we'll save a "manifest" file into the destination directory. This file will contain the information needed to cleanly upgrade to a new version of the template in the future. It contains the template location, inputs, and hashes of all the output files. Example:


# Generated by the `abc templates` command, do not modify
template_location: 'github.com/abcxyz/abc.git//t/template_name'
template_hash: '24bda78ab23...'  # Recursive directory hash of template
inputs:
  gcp_project_id: '12345'
  service_account: 'foo@bar'
hashes:
  - file: 'main.tf'
    hash: 'sha256:1a2b3c4d5e6f...'
  - file: 'terraform.tf'
    hash: 'sha256:968ad987e87fb9...'

The manifest file will be named .abc/manifest_.lock.yaml. It will be placed in the template destination directory (which is usually the CWD where the user runs abc templates ...).

We'll add a new command:

templates upgrade [--force-overwrite] [--input=foo=bar] [--abort-on-conflict] [--location=github.com...] <manifest_filename>```

This will:

1. download the latest version of the template
2. if the template hasn't changed (its dirhash is the same), then exit with a message
3. render the new template with the inputs that were saved in the manifest
4. merge the new template output with the existing files in the filesystem. For each file in the new template output:
   a. If there's no existing file at that path, just save the new output file.
   a. If there is an existing file at that path, but it hasn't been customized (the hash matches the hash in the manifest), then overwrite it with the new file.
   a. If the file HAS been customized (its hash doesn't match the manifest), then call this a "conflict." Tell the user to manually merge the existing/old file with the new file. We'll put the old/existing file at $FILE.old and the new file at $FILE.new...
   a. If there was a file that was generated by the old version of the template that is not generated by the new version of the template: delete it if it wasn't customized, or tell the user to handle the conflict if it has been customized.

Flags:

• --abort-on-conflict: if the upgrade can't apply cleanly due to customizations, abort rather than ask the user to resolve the conflict.
• --force-overwrite: overwrite all output files, even if they have been customized by the user.
• --input=foo=bar: two use cases:
  • provide any inputs that are required by the new template that weren't part of the original template
  • override any input values that were in the manifest, and use the new value instead when executing the new template.
• --location=github.com/x/y.git?some/template?ref=v1.2.3: in the case where the local template is pinned to a specific ref (like ?ref=some_old_tag , then the user will need to include this flag to specify the new ref to upgrade to.

### Alternatives considered

_No response_

### Additional information

_No response_