Alternative to Mallard and library-web for the release notes?

The past few releases have been fairly patchy when it’s come to writing the release notes. As a result, despite my attempts to try and not do them, I get the feeling that I’m going to end up doing a bunch of the writing for 41.

I would love for us to be able to move away from the old tooling for the GNOME 41 release notes. Writing them in Mallard is painful. Publishing them using library-web doesn’t look great, and is not sustainable in the long term.

Historically, I think that the main arguments for Mallard + library-web were:

  1. It kept the release notes in one place
  2. They could be translated using our standard translations infrastructure (looking at recent releases, we do seem to consistently get translations for around 14 languages)

Are there any other publishing platforms that we could use that support translations? Personally I’d be fine with something like a blog or a static website.

I’m guessing the new documentation site cannot be used? I’m not sure if the new site uses translations. As GNOME 41 is soon, it might not be enough time to have something which does translations. Especially something integrated with the GNOME translator workflow. So maybe an idea to use something even if it has a few drawbacks for GNOME 41.

The new docs site uses Sphinx. A cursory look seems to suggest that it does support translations, and would be compatible with our tooling (it uses gettext).

That said, I would prefer to avoid Sphinx if we can. I don’t think we need the features that a docs framework brings with it, and I’d prefer to put the emphasis on presenting the content in a way that looks really good.

3 Likes

If you are looking for a simple static site builder, then may be give Hugo a try? You can write the notes in simple markdown format and Hugo can publish it as a website using the provided theme (a lot of free themes are available and making up one from scratch isn’t that hard either).

Hugo also provides a pretty translation feature: Multilingual Mode | Hugo

For the record, Hugo multilingual support is not great and requires some workarounds to work with proper translation tools and workflows like the ones we use.

1 Like

A somewhat “middle of the road” solution: keep Mallard for GNOME 41, but drop library-web.

Library-web is just dead weight, at this point: we could replace it with GitLab pages and a CI pipeline, just like we did with the HIG and the developer documentation website.

I noticed that there’s already an issue open about using CI; I’d be happy to work on it. We can build the release notes for every previous releases as well, and publish them all into a single Pages space, and then ask the sysadmin teams to redirect help.gnome.org there.

This would give us at least another cycle to find a replacement for Mallard.

An issue somewhat related to release notes: when searching in Gitlab code repositories, the first several pages of results will often be the “NEWS” file, with no obvious way to exclude it. For example, look at this search for “gsettings” in GLib. By contrast, if you do the same search in the GitHub mirror, the “NEWS” file doesn’t immediately dominate the results, and you can easily filter by file type.

Granted, this is a Gitlab issue, and I should probably look into there being a Gitlab “Issue” issue on their platform ticket system, but there are currently 6,564 results for the word “search” in the Gitlab platform issue tracker, so that’s kind of overwhelming to navigate.

Depending on how Gitlab code searches work, as a short-term fix, appending a .md or .rst extension to files like “NEWS” and “README” might help keep them from mixing in with and dominating code search results. (This particular issue is not present if you’re doing a local search in a cloned repository. Different IDEs obviously have their own issues instead.)

In general I just completely hate Gitlab’s search function, but this isn’t exactly the place to rant about it, lol.

I just created a probably excessively salty issue on the Gitlab issue tracker.

In that approach we’d write a new tool to convert the Mallard to HTML?

No, my proposal only replaces library-web in the chain. I don’t have a good replacement for Mallard in mind that satisfies the requirements of being easier to write and style, and yet translatable within our infrastructure.

There is some work being done to convert the build system from autotools to meson. If I recall correctly, library-web is only able to build the release-notes using autotools, so a move away from library-web might align nicely with porting the build system to meson.

I think dropping library-web is a reasonable first step, but we need to identify an alternative before we can drop it. I think for GNOME 41, things need to remain as they are. And start the migration off library-web for 42?

A replacement for library-web:

  • add a .gitlab-ci.yml to every branch of the release-notes repository; the CI pipeline for every branch will:
    • build the release notes into HTML
    • store the build inside the pipeline artefacts
  • add a “help-gnome-org” branch to the release-notes repository; the CI pipeline for this branch will:
    • list all the branches that need to be published and map them to their corresponding GNOME version
    • download the pipeline artefact for each branch as a zip file
    • unzip the contents of the artefact into a public/<version> directory
    • set the entire public directory as a pipeline artefact, to let GitLab publish it under the “pages” space

The end result would be that all the release notes would be available at teams.gitlab.gnome.org/engagement/release-notes/<version>. At that point, we can have the sysadmins add a proxy that would make the help.gnome.org/misc/release-notes/<version> URIs go to the GitLab pages instead of library-web.

As I said, this is pretty much the same thing we’re doing now for doc.gtk.org.

1 Like

Actually, digging a little deeper, I see that Bastien already did the initial leg work on building in CI.

https://gitlab.gnome.org/Teams/Engagement/release-notes/-/merge_requests/36

Just curious - is it still painful using the lightweight Ducktype syntax rather than XML? I wrote quite a lot of Mallard XML for documentation and I can see why that would be considered painful.

My take on the release notes is that I actually like mallard + yelp for writing them. Switching to some complex cms’y thing would seem like a step back for a selfcontained document like the release notes. I don’t find writing in mallard painful at all.

Yes, there are advantages to being able to use standard infrastructure and tools (Git, Gitlab, your editor of choice).

The pain for me with Mallard is largely due to the syntax and tooling. It’s seriously verbose (I wasn’t being hyperbolic when I said it was painful - all the arrow brackets make my fingers hurt). I end up spending an unreasonable amount of my time debugging the markup, which is partly due to the lack of decent tooling. And there’s no good way to get a preview of your document as you type (try to use Yelp for this; it constantly crashes).

Writing this makes me wonder if I was wrong to discount Sphinx above. Yes it would be an odd choice, given that we don’t need the features of a docs framework, and given that you don’t get a huge amount of freedom when it comes to styling. But what it would give us is a familiar workflow using standard infrastructure, the ability to keep the content and the styling separate, and some decent tooling. I was hoping to find a web framework that has the same characteristics, but maybe this would be good enough.

I’ve briefly looked at Ducktype in the past, but have never actually used it to produce anything. One thing that put me off was the lack of documentation… it never looked particularly mature to me.

(try to use Yelp for this; it constantly crashes).

That is https://gitlab.gnome.org/GNOME/yelp/-/issues/174

Jakub has kindly had a go at setting up a Sphinx-based release notes website. It’s currently using Markdown rather than ReStructuredText. Seems possible to use gettext with it.

This looks incredible. The pipelines are easy to understand, and the source is very straightforward to read. I’m on board with this as a release notes website. How does sphinx handle translations? We need the buy-in from all our translators though.