State of min_version in theme.toml for community themes

1

I cloned the official Zola themes repository and ran this over all theme.toml files:

MIN_PAT="0\.\d+\.\d+" && rg -g "**/theme.toml" -NIo "min_version\s*=\s*\"$MIN_PAT\"" | rg -o "$MIN_PAT" | sort -V | uniq -c | uvx termgraph

This produces the following distribution:

0.1.0 : ▇▇▇▇ 2
0.4.0 : ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 23
0.4.1 : ▇▇ 1
0.5.1 : ▇▇ 1
0.6.0 : ▇▇ 1
0.8.0 : ▇▇▇▇▇▇ 3
0.9.0 : ▇▇▇▇ 2
0.10.0: ▇▇ 1
0.10.1: ▇▇ 1
0.11.0: ▇▇▇▇▇▇▇▇▇▇▇▇▇ 6
0.12.0: ▇▇ 1
0.13.0: ▇▇ 1
0.14.0: ▇▇▇▇▇▇ 3
0.14.1: ▇▇▇▇▇▇ 3
0.15.0: ▇▇▇▇▇▇▇▇▇▇▇▇▇ 6
0.15.3: ▇▇ 1
0.16.0: ▇▇▇▇ 2
0.16.1: ▇▇▇▇ 2
0.17.0: ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 11
0.17.1: ▇▇ 1
0.17.2: ▇▇ 1
0.18.0: ▇▇▇▇▇▇▇▇▇▇▇▇▇ 6
0.19.0: ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 14
0.19.1: ▇▇▇▇▇▇ 3
0.19.2: ▇▇▇▇▇▇▇▇▇▇▇▇▇ 6
0.20.0: ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 10
0.21.0: ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 7
0.22.0: ▇▇ 1

The most striking thing here is the large spike at 0.4.0 (23 themes).

Zola 0.4.0 is old; it was still called gutenberg back then. Out of the 23 themes claiming min_version = "0.4.0", only 3 actually worked when built with that Zola version. A likely explanation is that many authors copied the theme.toml template from the documentation (which uses 0.4.0) and never updated it.

Doesn’t min_version imply: “This theme runs on at least this Zola version, and all newer ones”?

But with all the breaking changes Zola has had over the years, that assumption is no longer safe. In practice, many themes only work on some much newer version, even if min_version refers to an older version. So today, min_version is often misleading rather than helpful.

I’m not criticizing individual theme authors; this looks like a tooling and metadata problem.

Is there anything we could do to improve this?

Some ideas:

  • A tested_with (array) field
  • A CI job in the themes repo that tries to build each theme with the current Zola
  • Or at least guidance for authors to bump min_version when they update for new breaking changes

Yes, the themes are maintained by their authors, and if they don’t update their theme.toml files, there is little we can do.

I’m not proposing anything specific. I just think the data shows that min_version in its current form is not doing what people intuitively expect it to do.

2 Likes
2

Yeah I am thinking of adding some kind of build check action in themes repo and remove outdated themes. The next release is very likely going to break every single theme so it should be a good clean start.

Edit: I meant removing them from the generated output and only if it’s not fixed after a while from the repo

3 Likes