Is moving all the documentation files around a major change from a packaging point of view?

[pwithnall (Philip Withnall)]

Hi all, looking to get some quick input from packagers here, about a necessary change in GLib.

See docs: Reduce nesting of documentation directories (!3964) · Merge requests · GNOME / GLib · GitLab

The proposed change is to remove one level of nesting in the installed docs files, e.g. files in /usr/share/doc/glib-2.0/gio move to /usr/share/doc/gio-2.0, etc. This is the best approach we’ve found to fixing the fact that in 2.80.0 the *.devhelp2 files installed by GLib are not found by Devhelp (so the documentation doesn’t show up there). That’s a fairly big problem.

Is this change to the nesting a big one from a packaging point of view, i.e. one which you would hate to see in a micro (2.80.1) release? Or is it actually fine?

It it’s a big issue then my proposal would be to hack around the Meson inside GLib to move the generated *.devhelp2 files after generation but before installation, so they are de-nested but the rest of the docs aren’t. Ship that for 2.80.1 but ship the fix proposed above for 2.82.x. I’d rather not do that though, as that will involve hours of my life fighting how both gi-docgen and Meson are designed to work.

[mcatanzaro (Michael Catanzaro)]

It’s sometimes annoying when files move around, but it’s not more or less effort to deal with for 2.80.1 than it would be if delayed until 2.82. 2.80 is still brand new, and it’s better to fix things sooner rather than later. Certainly the docs moving around is less annoying than the documentation being broken.

@pwithnall

It it’s a big issue then my proposal would be to hack around the Meson inside GLib to move the generated *.devhelp2 files after generation but before installation, so they are de-nested but the rest of the docs aren’t. Ship that for 2.80.1 but ship the fix proposed above for 2.82.x. I’d rather not do that though, as that will involve hours of my life fighting how both gi-docgen and Meson are designed to work.

I would move everything to its final intended location now for 2.80.1, so packagers don’t have to adjust things once again in 2.82.

[jbicha (Jeremy Bicha)]

I agree with Michael. I hope that this lands earlier than GNOME 46.1 because GNOME 46.1 is too late to get into the initial Ubuntu 24.04 LTS and Fedora 40 releases. I think it’s easier to rearrange distro packaging before the distro stable release happens.

[pwithnall (Philip Withnall)]

Thanks for the input. Let’s get the change in the 2.80.1 release, then. The GLib release schedule generally leads the GNOME one by a couple of weeks (subject to person power to actually do the releases). The milestone dates are public. Currently 2.80.1 is scheduled for 2024-04-18, which is actually only a couple of days early. I’ll move it to 2024-04-04 if that would work better?

[pwithnall (Philip Withnall)]

Distros are also, of course, welcome to carry the patch themselves from the point it’s reviewed and merged in GLib main, if that would help with distro release timetables and stability.