Versioning the spec

[symac]

Looking at the current issues of this repo, it seems that some enhancements to the current spec will arrive sooner or later. Not sure that everything will be doable using just extra syntax and at some time there might be breaking changes.

It might be a good idea to have a standardized way to declare in a .cook file which version of the spec have been used to describe the recipe?

[dubadub]

Thanks! It's a great idea and we keep this in mind. We might go with that if we introduce some big breaking change.

[bubonicfred]

If we want to follow semver, major version 0 is considered unstable with breaking changes at any time.

[Julienlego]

Why not have this in the metadata? Something like ">> Ver: 0.1" or idk. If the version of the spec used in the recipe should be declared somewhere in the .cook file, I feel like it should be in the metadata, maybe even as a reserved keyword.

[jnmclarty]

I think putting it in the metadata will be sub-optimal.

1. There could be breaking changes to the way metadata is, itself parsed.
2. If you put it in the metadata, you have to scan the entire document, searching/hunting for the version. This hurts performance, cost money, and therefore the user experience.

I would submit a couple counter proposals:

Proposal A - # lines

• Ignore any line at the top of a file that start with # until there is a line that doesn't start with #.
• Add # cooklang.org/spec/v0.0.0.1 to the top of a file.

Pros

A parser could parse any file, reading the first lines, without needing to check information. .cook file or .yaml, both would work.

Cons

We're overloading #'s usage in the spec, in order to make the file format performantly compatible with parsing yaml.

Proposal B - -- lines

• Ignore all the lines that start with -- until it hits a line that doesn't start with --. That is, if you add comments to the top of file, and those would be ignored by all parsers. (Do some parsers actually display/render comments to the user?)
• Add -- cooklang.org/spec/v0.0.0.1 to the top of a file.

Pros

Backwards compatible.

Cons

If some users put a comment at the beginning of a file, it would be "lost" (if their app is actually rendering comments).

Note

In either case, I would ask the spec-maintainers to consider extending the "initial ignored" lines for either proposal above, to N-number of ignored lines. The logic is, on a per-app, or per-client, basis, there may be other information an app may want to store alongside the individual file, intentionally avoiding making a new (rider) like file. The two things I can think of, are more selfish for the app I'm building, but I think many app-maintainers would have their own use case for per-recipe extras.

[jnmclarty]

I may or may not be confused by a difference between the spec and the implementation of a specific parser. Apologies if my proposals above are confusing/corrupted by an incomplete picture of the spec.

[ringods]

Do have a look how static site generators like Hugo model document metadata as TOML, YAML or JSON frontmatter:

https://gohugo.io/content-management/front-matter/

Where Markdown is the content format for static sites, it is CookLang here. TOML and YAML have broad programming language support.

So please, let's not reinvent the wheel on defining yet another metadata format. 🙏🏻

[dubadub]

That's actually a very good idea! I'm all for not reinventing the wheel 👍