whiskers version compat metadata

[nekowinston]

Since we're kinda writing and improving whiskers as we're using it to template files in the org...
It would be useful to have a semver range that whiskers respects, e.g.

whiskers-version: ">=1.2.0, <2.0.0"

Parsed with semver so we can iterate quickly without breaking old files; would be nice if whiskers wrote its own MAJOR back into the template, so breaking changes are enforced that way.

This is especially useful if we intend to add external/predefined data in MINOR releases, because yeah, they're not breaking changes, but someone running an older version of whiskers against a shiny new Whiskers template would lack context data.

[sgoudham]

I can think of 2 routes we can go down here:

1. We enforce that all templates must contain the whiskers-version key:

   ---
   whiskers-version: "<string>"
   ---
   # rest of file here

   Effectively, this means that no matter what file is chosen, it will always have a frontmatter block with the version. This results in a bit of extra effort on the programmer when they create the template to specify a semver-compatible string.

2. We accept template files without the whiskers-version key, log out a warning saying that we're going to attempt to parse it even though no version has been set.

   • If it fails: we log a failure and say that it could be due to no version being set, and proceed to prompt them to specify a version
   • If it succeeds: we write the current $CARGO_PKG_VERSION back into the template under the key whiskers-version

Personally, I prefer 1. because it avoids a lot of extra complexity in the codebase for relatively little effort on the programmer's side to specify a version upfront, but I could be missing something here that makes 2. worth it.

What do you think?

cc: @backwardspy

[backwardspy]

i think i actually like #2 better as it's significantly easier on users. i would prefer that they don't have to know which whiskers version they have or how our versioning scheme works, since whiskers already knows that and can generate a valid semver range itself. it should log a message saying that it's found an unversioned template and then update it for you if it parses successfully.

i don't love messing with the users' frontmatter since it'll probably rearrange/reformat it, but this is something that should happen super early in the process so hopefully that's not a big deal.

[sgoudham]

Closed via #150