Proposal to change how we record versions

[Shaun McCance <shaunm gnome org>]

Hi all,

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.

I'm very interested in people's opinions on this. I want to make sure
that status tracking is actually useful and helps us keep our docs
current.

Thanks,
Shaun