From https://etherpad.gnome.org/p/docs-fosdem-2020 by @davidk with edits from @shaunm and @pmkovar :

Problem

Understand the difference between stable and old branches, and master, so that we do not have to manually specify those versions.

Currently, branches must be manually specified for each module in https://gitlab.gnome.org/Infrastructure/help.gnome.org/-/blob/master/pintail.cfg.

Stable and unstable links

• Have a stable symlink that always points to the latest stable version?
• Make the stable symlink the default when browsing by application (toplevel help.gnome.org)
• Links from/to stable and unstable versions

Figure out GNOME stable branching scheme

We could take the latest stable tag, and build from that, but as we have a system in place where no changes to translations happen on stable branches (without prior agreement from the translation teams), it is sufficient to take the latest commit from the stable branch, and use that

Options for using GNOME stable branching scheme

GNOME has the concept of a development branch (master), a stable branch (latest branch that follows the gnome-x-yy scheme) and oldstable branches (older branches in the same scheme). Pintail has the concept of a directory, which maps 1:1 to a result, so a separate branch is represented as a separate directory. Rather than abusing the git directory plugin to subvert the 1:1 mapping, we could use a configuration file generator, to take a list of modules, enumerate the branches under the GNOME scheme and generate a Pintail configuration using the existing git plugin. The better fix may be to create a DirectoryFactory interface, that could resuse the configuration file generator logic to create a list of Pintail directories from a list of git modules.

gtk-doc has a markdown-to-docbook "parser" (gtkdoc/md_to_db.py) that could be used to take documentation strings from GIR files, parse them into docbook, and then generate a static documentation site in HTML from them. It even has tests! (tests/mk_to_db.py) The gtk-doc markdown strings are included as a "doc" element in the GIR files, but parsing the whole file is probably required to get the required context for crossreferences, etc.

Proposed scheme

Current stable:

• help.gnome.org/gnome-help/
• help.gnome.org/cheese/

Unstable:

• help.gnome.org/unstable/gnome-help
• help.gnome.org/unstable/cheese

Add these later if previous versions are needed (downstream distros or ISVs might need access to old versions for their users):

• help.gnome.org/3.36/gnome-help
• help.gnome.org/3.34/gnome-help