Re: Proposal to change how we record versions

[Shaun McCance <shaunm gnome org>]

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