Eleventy: Questions about Included Libraries, Documentation, upgrades, etc

[cfjedimaster]

Please pardon me if this rambles a bit. I will absolutely be ok breaking this into smaller issues, ERs, and so forth. This is kind of broad and I wanted a place to lay out some thoughts and get feedback. I also want to _help_ with this as well so please take this as me volunteering as well. Anyway, sorry for the long pre-amble.

I was helping out a user on Twitter who was trying to use something in Liquid that is only supported in a new version than 11ty ships.

So question 1 - where do we document the version of included libraries? At least for Liquid (https://www.11ty.dev/docs/languages/liquid/) it is not documented. I'm sure it exists somewhere, but it should absolutely be documented on each individual template language page. You do specify how to supply your own, but as a user, I don't even know what version is being included.

Question 2- based on this issue (https://github.com/11ty/eleventy/issues/469), is there a "policy" for Eleventy in terms of how to handle updates? So for example, if Eleventy used Liquid version 1.01, and a security issue was found and fixed in 1.02, I assume Eleventy would quickly bring that in, right?

If v2 comes out and has no breaking changes, when would you roll it in? Do you check like once a month or so, or wait for a PR?

If v2 has breaking changes, it looks like you attempt to make it backwards compat. That's noble, but I have to say I'd also (well, as one user of Eleventy :) be ok with the understanding that my code may break if I upgrade Eleventy and it includes a newer Liquid. If it happened a lot, I'd blame Liquid more than Eleventy, but I can totally understand where you (you being everyone behind Eleventy) may not want that grief.

Question 3 - it feels like this issue as a whole should be it's documentation page. Ie, "This is how we handle versions, updates, breaking changes, etc." Agreed? If so I'd volunteer to take a stab at writing it.

Thank you for listening.

[DirtyF]

npm outdated is no docs, but here's the current state:

Package      Current  Wanted  Latest  Location
ejs            2.7.4   2.7.4   3.0.1  @11ty/eleventy
handlebars     4.7.1   4.7.3   4.7.3  @11ty/eleventy
liquidjs       6.4.3   6.4.3   9.6.2  @11ty/eleventy
mustache       2.3.2   2.3.2   4.0.0  @11ty/eleventy

Maybe the current version of each templating languages used in the package.json could be extracted and displayed in the docs?

I don't know how strictly Eleventy adheres to semantic versioning, but anything before v1.0 should be considered unstable right?

[Ryuno-Ki]

Fun fact: npm has a --json flag, which produces machine-readable output:

npm outdated --json (undocumented IIRC).

This is how we handle versions, updates, breaking changes, etc.

I'd expect that to be a markdown file.

[pdehaan]

FYI, npm outdated is documented here: https://docs.npmjs.com/cli-commands/outdated.html

[zachleat]

strictly Eleventy adheres to semantic versioning

Eleventy will adhere to semantic versioning but ignore the pre-v1.0 exceptions because I think those are silly. Our next version will be 1.0 to make this more consistent.

[cfjedimaster]

To handle part one of this issue, and assuming it can't be automatic, may I do a PR on the docs that adds the version #s for template language libraries?