-
-
Notifications
You must be signed in to change notification settings - Fork 491
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add version of template language plugin packages on 11ty docs #906
Comments
Maybe the current version of each templating languages used in the I don't know how strictly Eleventy adheres to semantic versioning, but anything before v1.0 should be considered unstable right? |
Fun fact:
I'd expect that to be a markdown file. |
FYI, npm outdated is documented here: https://docs.npmjs.com/cli-commands/outdated.html |
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. |
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? |
Ran into this again today. :) Once 1.0 lands, I'd like to revisit this and add the explicit versions to the docs. |
Probably doesn't help anybody, but I was curious how easy [part of] this would be to scrape from the package-lock.json file on a clean install and via npm info [package name] --json:
const cp = require("child_process");
const packageLock = require("./package-lock.json");
const packages = ["ejs", "hamljs", "handlebars", "liquidjs", "nunjucks", "pug"]
main("@11ty/eleventy", packages);
async function main(name="", packages=[]) {
const eleventy = packageLock.dependencies[name];
console.log(`${name} v${eleventy.version}\n`);
console.log("| Package | Requested | Actual | Latest |");
console.log("|:--------|:---------:|:-------|:-------|");
for (const package of packages) {
const version = packageLock.dependencies[package].version;
const info = getPackageInfo(package);
const pkgTime = info.time[version];
const latest = info["dist-tags"].latest;
console.log(`| ${package} | ${eleventy.requires[package]} | ${version}; ${localeDate(pkgTime)} | ${latest}${version !== latest ? `; ${localeDate(info.time[latest])}` : ""}`);
}
}
function getPackageInfo(name) {
const res = cp.execSync(`npm info ${name} --json`);
return JSON.parse(res);
}
function localeDate(date) {
date = new Date(date);
return date.toLocaleDateString();
} Usually if I need to remember which exact/resolved version of liquidjs I'm using in 11ty stable/v0.12 channel, I just do something like this (either in my .eleventy.js config for debugging, or I'll export it in a global data file if I plan on exposing it to 11ty templates): const {name, version} = require("liquidjs/package.json");
console.log(name, version); |
Turns out I can use pacote and david to check for outdated modules without even having to install Eleventy locally, which means it's pretty easy to quickly check v0.10, latest, canary, etc. const promisify = require("util").promisify;
const david = require("david");
const pacote = require("pacote");
// Convert callback API to promises.
const getDependencies = promisify(david.getDependencies);
main("@11ty/eleventy@canary", ["ejs", "hamljs", "handlebars", "liquidjs", "nunjucks", "pug"]);
async function main(nameVersion, pkgFilter) {
const manifest = await pacote.manifest(nameVersion);
const deps = await getDependencies(manifest, {stable: true});
console.log(`${manifest.name} v${manifest.version}`);
listDependencies(deps, pkgFilter);
}
function listDependencies(deps, pkgFilter) {
// Flatten and sort deps object.
deps = Object.entries(deps)
.map(([name, obj]) => Object.assign({name}, obj))
.sort((a, b) => a.name.localeCompare(b.name));
if (Array.isArray(pkgFilter)) {
deps = deps.filter(dep => pkgFilter.includes(dep.name));
}
console.log("Name | Required | Stable | Latest\n-----|----------|--------|-------");
for (const dep of deps) {
console.log(`${dep.name} | ${dep.required || "*"} | ${dep.stable || "None"} | ${dep.latest}`);
};
} @11ty/eleventy v0.12.1
@11ty/eleventy v1.0.0-canary.37
Although, that just tells me about package.json manifest and it's semver range. Not sure if there is an easy/good way to determine which final version of a package would be installed without, like, installing Eleventy and seeing which final version of LiquidJS got installed. UPDATE: It's too hot outside, so I think I solved my issue using pacote and semver: const pacote = require("pacote");
const semver = require("semver");
main("@11ty/eleventy", ["ejs", "hamljs", "handlebars", "liquidjs", "nunjucks", "pug"]);
async function main(pkgName="", engines=[]) {
const packument = await pacote.packument(pkgName);
const distTags = packument["dist-tags"];
for (const [distTag, version] of Object.entries(distTags)) {
if (distTag === "latest") {
continue;
}
if (semver.lt(version, distTags.latest)) {
// Delete a dist-tag if it is older than the "latest" stable release version.
delete distTags[distTag];
}
}
for (const [tag, version] of Object.entries(distTags)) {
const v = packument.versions[version];
v.tag = tag;
console.log(`\n${v.name} v${v.version} (${tag})`);
for (const engine of engines) {
const engineVer = v.dependencies[engine];
const maxVer = await getMaxSatisfyingSemver(engine, engineVer);
console.log(` ${engine}@${maxVer} (via ${engineVer})`);
}
}
}
async function getMaxSatisfyingSemver(name, pkgSemver) {
const packument = await pacote.packument(`${name}@${pkgSemver}`);
const engineVersions = Object.keys(packument.versions);
return semver.maxSatisfying(engineVersions, pkgSemver);
} OUTPUT
|
Nice. Could |
Possibly, if we wanted to add some CLI flag that would display the various engine version numbers for the currently installed Eleventy. I was inspired to build https://github.com/pdehaan/11ty-engine-versions over the weekend, which tries to fetch some package metadata and figure out version numbers like in my nonsense code above (but now it's a library I can install via npm/GitHub). Plus, this way I can use it with an Eleventy global data file and/or pagination, like https://pdehaan.github.io/11ty-engine-versions-test/. I think one of my biggest concerns is that sub dependency versions can change at any time, so the page might need to be rebuilt occasionally (or I could create a GitHub Action on a cron job which rebuilds and pushes to GitHub pages nightly). Or maybe it will inspire me to investigate the new Eleventy Serverless stuff @zachleat has been working on. |
Just to circle back here on template engine breaking features, it depends on a few things! We do document all major version bumps in our dependencies (not just for template languages) and the reason provided by the dependency for that bump: e.g. https://github.com/11ty/eleventy/releases/tag/v0.12.0 and https://github.com/11ty/eleventy/releases/tag/v0.11.0 If it’s a Node minimum version in the dependency that is already below our advertised Node support, I would include that and would not consider it an Eleventy breaking change. For 1.0 we will have an upgrade helper plugin: https://github.com/11ty/eleventy-upgrade-help Does that sufficiently answer the questions here? |
|
"Does that sufficiently answer the questions here?" I'd say no, because in order for a developer to find out what version Eleventy is using, they would need to go into the release tag notes, when it really should be in the top level docs for each template, right? So for example, when I go here: https://www.11ty.dev/docs/languages/liquid/ To me it makes sense for that kind of information to be more readily available. Yes, it -is- available now, but let's float it up a bit. :) |
Good feedback! I think the action item here then is to prominently display the current version of each template language on the docs on their individual pages |
Not sure how this works though. Should the docs say "Eleventy 0.12.1 ships with LiquidJS ^6.4.3" (with a generic semver range from the package.json)? Or how would the docs know if I'm on 0.12.1/latest vs a Canary build? |
I'd assume that the docs would always talk about the current version. So if Eleventy 1.0 ships with Liquid 10, and Elevent 1.X to 1.9 never changes that, then there's no need to edit the doc. Basically - the assumption is the current version of Eleventy. |
Yeah, that makes sense. I was just imagining the cases where the docs mention upcoming 1.0 features (https://www.11ty.dev/docs/data-global-custom/), but that says "Coming soon in v1.0.0". But I agree that it's probably best to just target the stable/latest version of 11ty and if somebody is running a beta or canary build, they can peek at the repos package.json file or something to get a semver range, if needed. |
Heh, well, imo, the docs shouldn't have that. To me it's confusing and should be kept to blog posts, or a dedicated "Coming Soon" page. As a reader, don't make me think. if I see, "this is a feature", I should always assume it's the released version. But - that's another issue and I figure I'm in the minority there. ;) |
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 (#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.
The text was updated successfully, but these errors were encountered: