docs: update docs to refer to new fetch:template action

Signed-off-by: Mike Lewis <mtlewis@users.noreply.github.com>

docs/features/software-templates/adding-templates.md

@@ -51,7 +51,7 @@ spec:
   steps:
     - id: fetch-base
       name: Fetch Base
-      action: fetch:cookiecutter
+      action: fetch:template
       input:
         url: ./template
         values:

docs/features/software-templates/builtin-actions.md

@@ -14,3 +14,39 @@ Azure, GitLab and Bitbucket.
 A list of all registered actions can be found under `/create/actions`. For local
 development you should be able to reach them at
 `http://localhost:3000/create/actions`.
+
+### Migrating from `fetch:cookiecutter` to `fetch:template`
+
+The `fetch:template` action is a new action with a similar API to
+`fetch:cookiecutter` but no dependency on `cookiecutter`. There are two options
+for migrating templates that use `fetch:cookiecutter` to use `fetch:template`:
+
+#### Using `cookiecutterCompat` mode
+
+The new `fetch:template` action has a `cookiecutterCompat` flag which should
+allow most templates built for `fetch:cookiecutter` to work without any changes.
+
+1. Update action name in `template.yaml`. The name should be changed from
+   `fetch:cookiecutter` to `fetch:template`.
+2. Set `cookieCutterCompat` to `true` in the `fetch:template` step input in
+   `template.yaml`.
+
+#### Manual migration
+
+If you prefer, you can manually migrate your templates to avoid the need for
+enabling cookiecutter compatibility mode, which will result in slightly less
+verbose template variables expressions.
+
+1. Update action name in `template.yaml`. The name should be changed from
+   `fetch:cookiecutter` to `fetch:template`.
+2. Update variable syntax in file names and content. `fetch:cookiecutter`
+   expects variables to be enclosed in `{{` `}}` and prefixed with
+   `cookiecutter.`, while `fetch:template` doesn't require prefixing and expects
+   variables to be enclosed in `${{` `}}`. For example, a reference to variable
+   `myInputVariable` would need to be migrated from
+   `{{ cookiecutter.myInputVariable }}` to `${{ myInputVariable }}`.
+3. Replace uses of `jsonify` with `dump`. The `jsonify` filter is built in to
+   `cookiecutter`, and is not available by default when using `fetch:template`.
+   The `dump` filter is equivalent, so an expression like
+   `{{ myAwesomeList | jsonify }}` should be migrated to
+   `${{ myAwesomeList | dump }}`.

docs/features/software-templates/writing-templates.md

@@ -62,7 +62,7 @@ spec:
   steps:
     - id: fetch-base
       name: Fetch Base
-      action: fetch:cookiecutter
+      action: fetch:template
       input:
         url: ./template
         values:
@@ -289,8 +289,8 @@ template. These follow the same standard format:
 - id: fetch-base # A unique id for the step
   name: Fetch Base # A title displayed in the frontend
   if: '{{ parameters.name }}' # Optional condition, skip the step if not truthy
-  action: fetch:cookiecutter # an action to call
-  input: # input that is passed as arguments to the action handler
+  action: fetch:template # An action to call
+  input: # Input that is passed as arguments to the action handler
     url: ./template
     values:
       name: '{{ parameters.name }}'
@@ -317,20 +317,20 @@ output:
 
 ### The templating syntax
 
-You might have noticed in the examples that there are `{{ }}`, and these are a
-`handlebars` templates for linking and glueing all these different parts of
-`yaml` together. All the form inputs from the `parameters` section, when passed
-to the steps will be available by using the template syntax
-`{{ parameters.something }}`. This is great for passing the values from the form
-into different steps and reusing these input variables. To pass arrays or
-objects use the syntax `{{ json paramaters.something }}` where
-`paramaters.something` is of type `object` or `array` in the `jsonSchema`, such
-as the `nicknames` parameter in the previous example.
+You might have noticed variables wrapped in `{{ }}` in the examples. These are
+`handlebars` template strings for linking and gluing the different parts of the
+template together. All the form inputs from the `parameters` section will be
+available by using this template syntax (for example,
+`{{ parameters.firstName }}` inserts the value of `firstName` from the
+parameters). This is great for passing the values from the form into different
+steps and reusing these input variables. To pass arrays or objects use the
+`json` custom [helper](https://handlebarsjs.com/guide/expressions.html#helpers).
+For example, `{{ json parameters.nicknames }}` will insert the result of calling
+`JSON.stringify` on the value of the `nicknames` parameter.
 
 As you can see above in the `Outputs` section, `actions` and `steps` can also
-output things. So you can grab that output by using
-`steps.$stepId.output.$property`.
+output things. You can grab that output using `steps.$stepId.output.$property`.
 
 You can read more about all the `inputs` and `outputs` defined in the actions in
-code part of the `JSONSchema` or you can read more about our built in ones
+code part of the `JSONSchema`, or you can read more about our built in ones
 [here](./builtin-actions.md).