New Ubuntu release notes

Project Discussion
, ,
1

Ubuntu 26.04 LTS (Resolute Raccoon) comes with a big change to the way we write and publish release notes.

In short:

Discourse is no longer used. We’re aligning release notes with the rest of the Ubuntu product documentation, making them better structured and more suited for collaboration. We’re working on increasing the overall documentation standard.

You’ll find the release notes here: https://documentation.ubuntu.com/release-notes/.

Why our release notes weren’t great

Up until now, we used to publish Ubuntu release notes on Discourse. One post every six months: Noble, Oracular, Plucky, Questing. It’s become clear that Discourse isn’t meant for this, and that we need to establish better documentation standards.

Problems with Discourse

For one, there are actual scaling issues. Some of our release notes get so long that Discourse refuses to publish the post, and we’ve had to split some into multiple posts.

Next, there are collaboration and versioning issues. Editing release notes meant overwriting another user’s Discourse post over and over, which is a privileged action that only users with high permissions can do. If an edit was problematic, there was no easy way to revert to an earlier version of the post: once I accidentally overwrote the release notes without refreshing my browser, which caused newly written release notes to be lost. The solution required us writing a Python script that could revert the post through the Discourse API.

Even though Ubuntu is a community project, there wasn’t a clear way for community members to contribute to the release notes. They couldn’t edit a locked post.

Finally, the Markdown implementation in Discourse is relatively lightweight. It’s fine for shorter posts but not for deeply structured documentation. For example, we wanted to have headings with anchors and a table of contents based on these. We had to resort to using HTML heading tags in the Markdown code.

Lacking documentation standards

Looking at it through the eyes of a technical author, the release notes were missing any sort of information architecture. Isolated posts are published, and they do come with the right content, but how do you find them? Suppose I’m only now upgrading from Ubuntu 22.04 LTS to Ubuntu 24.04 LTS. My best bet is searching on the web or on Discourse. The download page contains links to the relevant release notes, but they’re easy to overlook, and you aren’t downloading when you’re upgrading anyway.

The URL to the release notes isn’t guaranteed to be predictable, either. Compare:

Discourse also contains release schedules (e.g. Resolute) and the changelogs for LTS point releases (e.g. Noble), which are related to release notes but aren’t interconnected with the other posts.

Speaking of LTS releases, our release notes didn’t clearly distinguish between the two different upgrade paths that might lead you to reading the release notes. The majority of Ubuntu users prefer to use LTS releases. On the other hand, the release notes tended to assume frequent interim upgrades. If you’re an engineer working on Ubuntu, it’s relatively easy to write about the features that you’ve delivered in the past six months, and it’s even easier to forget about the changes in the previous two years: you might not even have been working on Ubuntu then!

There needs to be a focused effort to let our LTS users know what news they’re getting when they upgrade, while our existing release notes often omit older information or make it unclear on which upgrade path the given change happens. Are “Ubuntu 26.04 LTS release notes” meant to list the changes since Ubuntu 25.10 or since Ubuntu 24.04 LTS? In our current setup, they try to do both and they blur the line.

General documentation quality standards could use more attention. I’m not even talking about enforcing Diátaxis rules – at minimum, we should ensure that there are no typos, the formatting is clean and the headings are consistent.

How we’re improving things

A new direction has been shaped by people at different positions: technical authors, the Ubuntu Release Team, UX designers, engineers and community members. We’ve tried various iterations and I believe that this is a step in the right direction, although still subject to change.

Technical improvements

We’re moving the release notes to Read the Docs, which is our new standard for product documentation. You’ll find a repository on GitHub at ubuntu/ubuntu-release-notes. The source is written in rich Markdown, specifically the MyST dialect, and the documentation is published on the Ubuntu website: https://documentation.ubuntu.com/release-notes/.

The Git versioning system enables safe collaboration and version management, even when hundreds of people want to edit the document a few days before the release. Community members only need a GitHub account to contribute, although there is a review process.

The links are predictable: documentation.ubuntu.com/release-notes/26.04/. The new architecture lets you browse all releases and find their schedules and point updates attached.

Content improvements

LTS releases and LTS upgrade paths now take the spotlight. The 26.04 release first gives you an overview of the major changes if you’re upgrading from the previous LTS. If you want to read all the details, you can review the four incremental steps:

Note that the 26.04 release notes are still incomplete. As for selecting what counts to be included in the LTS overview, we’ll have to get the hang of this and build a practice over time. Starting with Ubuntu 26.10, I want to establish a process where contributors tag what they think are the highlights of each interim release, and we can later collect those highlights in the upcoming LTS release notes. That should make it a little easier not to forget older changes.

The most significant change to the way we write release notes might actually be distinguishing the types of change. Since every Ubuntu release takes most of its new software from upstream, many of our release notes take the form of “project X was updated to version Y; see the upstream release notes.” Ideally, we should capture how these updates affect the user. Is there a breaking change in project X, version Y? Let’s list that note in the breaking changes section. Is it just a bug fix release and nothing more? List it in the bug fixes section. Warning of a known issue? There’s a section for that. This way, users can scan the document and easily tell if it’s safe for them to upgrade and which are the new exciting features.

release notes structure
release notes structure1593×869 112 KB

Differentiating between LTS and interim changes, as well as between the various change types, will make our release notes more concrete and easier to understand without a deep knowledge of each upstream component.

Thanks to the GitHub and Read the Docs setup, we also get some quality tests for free. A CI/CD pipeline checks for spelling issues, broken links and other problems. We have lots to fix.

How you can contribute

If you want to submit an Ubuntu release note, the easiest way is to file an issue.

The issue form (an experimental GitHub feature) guides you through writing all the information needed for a good release note. For example, if you’re describing a known issue, it reminds you to also provide a workaround that users can try.

If you feel comfortable navigating the source structure, you can also submit a pull request.

We also appreciate any feedback on the new format of the release notes. Keep in mind that the content is still somewhat in flux. Some notes are incomplete and some might be in the wrong place.

If you like digging through old wikis and mailing lists, you can help us gather all the old release notes via the Archiving issues on GitHub. Good hunting!

Further plans

Right now, the new release notes only cover several of the latest Ubuntu releases. We’d like to go back in history and gather a full archive in one place, going all the way back to Warty Warthog from 2004.

Automation is a huge topic for later releases. A lot of this work is very manual. GitHub issue forms could serve as a data source to be processed by some tools, but Launchpad also holds useful release information ready to be processed. Before we start implementing anything, though, we need to know where automation actually makes sense. Let’s keep an eye out for chores and error-prone tasks that can be automated.

19 Likes