Change how we record versions
I sent this to gnome-doc-list. I'm making an issue so it doesn't get lost.
https://mail.gnome.org/archives/gnome-doc-list/2020-September/msg00002.html
GNOME is changing its versioning scheme. The next major GNOME release will be GNOME 40:
https://discourse.gnome.org/t/new-gnome-versioning-scheme/4235
This is a good opportunity for us to change how we record versions in Mallard revision elements. Mallard provides three attributes to specify the version number: version, docversion, and pkgversion. There's some history that I won't go into, but the short version is that we aren't consistent. Different documents use different attributes. Some record just major-minor (3.38), and some record major-minor-micro (3.38.0). It's a mess.
There's an open MEP to change this in Mallard 1.2:
http://projectmallard.org/mep/mep0006
Basically, deprecate docversion and pkgversion, and allow version to take a space-separated list of version tokens. So, for example, you could do this:
<revision version="gnome:40 ubuntu:21.04 fedora:34" .../>
We would need to wait for Mallard 1.2 (and for tools to catch up) to do these version lists, but the good news is we don't need to wait for Mallard 1.2 to just start recording our versions like this:
<revision version="gnome:40" .../>
So, that's my proposal. With the coming release cycle, we stop using docversion and pkgversion, and always use the version attribute with the gnome: prefix. And you never include the minor version. You can then always check statuses with:
yelp-check status --version gnome:40 *.page
I also have a fairly simple online status tracker that will show you this information online. I'm going to ask to get this running on a GNOME server somewhere, but here's a preview:
https://people.gnome.org/~shaunm/docstatus/
There's an open question as to what non-core apps should do. Honestly, I think the answer is "whatever the maintainers want". If they're following the GNOME release cadence, and especially if the folks on this list work on the docs, they should probably follow this. But they could also just use whatever version numbers make sense for them.