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:
It kept the release notes in one place
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.
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).
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.
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.
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.
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?
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.
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.
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.