Re: Proposal to change how we record versions
- From: Shaun McCance <shaunm gnome org>
- To: gnome-doc-list gnome org
- Subject: Re: Proposal to change how we record versions
- Date: Thu, 29 Oct 2020 19:02:59 -0400
Hi folks,
I filed this as an issue in our new Initiatives space on GitLab:
https://gitlab.gnome.org/Teams/documentation/initiatives/-/issues/7
On Wed, 2020-09-16 at 14:17 -0400, Shaun McCance wrote:
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
_______________________________________________
gnome-doc-list mailing list
gnome-doc-list gnome org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list
[
Date Prev][Date Next] [
Thread Prev][Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]