Clarify that debos recipes are pre-processed using go templating before yaml parsing

[elboulangero]

Consider the following snippet in a recipe:

{{ $kver := "4.9.0" }}
#{{ $kver := "4.16.0" }}

Currently the value of kver will be set to 4.16.0, since the Golang templating engine is not aware of the YAML syntax. But this is definitely not what an user expects, comments should be ignored.

[smcv]

I'm not so sure this is a great idea. At the moment the processing model is reasonably easy to explain: the template undergoes Go templating evaluation, followed by YAML parsing. Applying a small fraction of YAML parsing, followed by Go templating evaluation, followed by full YAML parsing seems more confusing to me?

I think the source of confusion is that the recipes are sometimes described as YAML, which is not really true, because the templating instructions don't participate in YAML syntax. Instead, the recipes are Go templates that must output YAML.

[gctucker]

Use Go template comments maybe?
https://golang.org/pkg/text/template/#hdr-Actions

[elboulangero]

If a line starting with # is a comment, then everything that comes after the # should be safe to write, don't you think?

[gctucker]

# is not a comment in the Go template language, but this {{/* */}} is:

# The line below should not appear in the YAML output:
{{/* {{ $arch := "riscv" }} */}}

I've verified it with a debos recipe.

[elboulangero]

@gtucker, thanks for the example. Actually I understand that I can use Go template comments, but that's not the point I want to raise. I opened this issue because I care about the usability of the tool.

It appears than recipe files are both YAML format AND Go template language at the same time (smcv said it better above). So when you look at a debos recipe, what do you see? Maybe some users see a YAML file, some other users see Go templating at work. Some educated users see both and know how it works under the hood, but you can't expect that from new users.

Personally, the first debos recipes I've seen looked and behaved very much like a YAML file, and I had absolutely no idea what Go templating was. So I used it like a YAML file, and it was just fine, until I happened to comment a line containing a template, and then I lost an hour or two figuring out what the hell was going on. Then I became a bit more of an educated user :)

Every new user is different, sure, but I think that there's something confusing that could be improved here.

[smcv]

It appears than recipe files are both YAML format AND Go template language at the same time

No, they are a Go template that generates YAML. The difference between that and what I quoted is important.

You can't write a machine-readable language correctly unless you know what it is. It's the same as how you need to know whether you are writing Javascript or Javascript-embedded-in-HTML before you can write a less-than comparison using < (if in Javascript) or < (if in Javascript embedded in HTML); if you get it wrong (in either direction!) then your code won't work.

If new users think the recipes are YAML, the solution is for the documentation to be clearer about the recipes being Go templates that generate YAML.

[gctucker]

Maybe the convention for naming recipe files should be something else than just .yaml as this can be misleading too.

[sjoerdsimons]

Well if there is no go templating in there they are pure yaml indeed :). But yes it's a documentation not a technical issue, debos does as it's intended (which @smcv nicely explained).

Just looking around there is no clear convention in what to name go templates. E.g. the Helm best practises say it should be .yaml if it generates yaml (but there templates are in a template dir which gives a hint).. Others use .gothml and .goyaml which some editors recognize, While others (like the go vim plugin apparently) looks for .tmpl extension.

I'd personally be slightly in favour of .goyaml, but i'd be fine with a differntly colored bikeshed :).