How do the release notes come together?

One point of feedback we got over the release announcement of Fedora 39 was that our release notes were not ready for the release. In checking what is available it does seem like certain sections for sysadmins were clear. However, other areas like for desktop users is empty despite having Gnome 45 and Fedora Onyx as the biggest desktop user facing changes. In this case I tried pointing them to the changelog we use during development, but that’s not as clearly laid out as it would be if it lived in Docs.

Is there a special process for filling out release notes that’s tied to a release, or is the cadence for release notes that same as with the rest of Docs, which is that someone who knows what should be in there needs to take it upon themselves to enter it? I think it’s the latter, but I wanted to confirm. I guess this is kind of what we were already talking about in this other thread.

For my perspective, it would be nice to have polished release notes rather than having to point people to the changelog. They could be linked to in the announcement and for support on social media. Then people who want to learn more are already on Fedora Docs for more user information, whereas leading them to the wiki places them in a confusing workspace that’s not really meant for them. I suspect we all would prefer up-to-date release notes, but just giving my two cents.

2 Likes

That’s a long-standing issue for many releases. It got worse from one release to the next. Therefore, I initiated a Docs-subproject, to generate the release notes more or less automatically from the Change proposals. Unfortunately, we run a bit out of resources, and it didn’t work as good as expected. See Docs Team meeting today.

I analyzed the reasons for all these problems in my talk on Flock 2023 in Cork. Basically, it is a lack of coordination (or integration) between (technical) development and the creation of documentation. We are working to improve that. It would be good to receive support for this. It could be that not all developers and decision makers in Fedora really realize the importance and relevance of documentation.

Until now, the general procedure is, that interested (end) users (not necessarily the change proposal owner) take one of the change proposals and write the required release note for it. And if enough users do this, we will end up with complete release notes. It has been a long time since we at least came close to achieving this goal.

More information: Contributing to Release Notes](Contributing to Release Notes :: Fedora Docs)

Currently, writing the release notes is basically a one-person endeavor, which is not even nearly enough. It is thanks to the tireless efforts of @pbokoc that we have any kind of release notes at all.

I suspect so, too. To involve more (end) users is probably not the solution. In order to write a release note, you need in most cases a technical understanding of what is going on and how it affects use.

I think the only solution is to optimize the exchange and processing of information. I will start a corresponding project again next week. Please, support us and watch the Docs discussion.

2 Likes

We’re still working on this, but Objective Review: Each Edition has a story for each release should tie in here. I’d really like Workstation, Server, Cloud, IoT, and CoreOS to be proactive here — not just Changes, but what’s changed upstream, what the focus is, what people should know. I call out the Editions in particular because I think this should be a requirement for editions. Other spins, and other SIGs should also be encouraged to do the same.

1 Like

I’m a bit astonished here. I read the “Each Edition has a story” and we as Server WG decided for a “story” (unfortunately currently not yet complete for f39). But I took it as a marketing initiative. So we can write articles in Fedora Magazine or maybe other publications, Marketing Team can post on the various platforms about it, etc. I didn’t get from your posting that it was about the release notes, to release notes, too.

Regarding the Release Notes, it is first hand a list of changes and - if useful - how users should deal with a change. I think, something like “what’s changed upstream” is a nice to have (although I suppose Server or CoreOS are upstream itself), but it does not relieve us of the task of compiling as complete a list as possible of all the changes. And currently, we are a long way from that at the moment.

1 Like

Oh, i certainly intended it as a marketing initiative, but in a more comprehensive sense of marketing than just advertising. I didn’t have the release notes in mind specifically, but I think it would help guide the docs.

But, I also didn’t mean just now to imply that that would be the entire release notes.

1 Like

So, we just had a productive conversation with @pboy on the weekly IRC meeting, and decided to take it to the forums for a wider audience and further discussion.

Essentially, the Release Notes suffer from a problem where everything about them must be done manually. @darknao’s script, as it currently stands, can’t possibly help very much, because all it can do is copy certain sections from each Change page on the Wiki, and put them together into a text file. This has the following major limitations:

  • Descriptions in the Change pages have a different target audience than the Release Notes, they’re aimed at other Fedora contributors, FESCO etc., not end users.
  • The Release Notes field in the Change page template is seldom used at all. When Change owners use it, they usually just drop a single sentence and that’s it.
  • Other fields (Summary, Detailed Description, Scope…) are used somewhat interchangeably at times. This is fine for the target audience, but not for Release Notes, because ideally we want to take info only from certain sections, and when that info is in one we don’t use, the script will ignore it.
  • The info on the Change page overall tends to be of varying quality, from a language standpoint.
  • The Release Notes are split into a bunch of sections for readability, but there’s no way for a script to determine which Change goes into which section, so it can only output one or two text files, and someone has to copy-paste each relnote to where it belongs.

Now, I told Peter that I have some plans for the next release (F40):

  • Clean up existing issues (close F37 and earlier) and merge or close open PRs
  • Move the repo to gitlab and clean it up (master → main, update the structure and the builder script)
  • While doing ^, flatten the document structure.

Regarding the last point: Up until now the Release Notes have been split into a bunch of pages for historical reasons - long pages made things hard to find. Now, thanks to Darknao’s implementation of an autogenerated, floating table of contents for each page, it’s fine to include a ton of separate relnotes on a single page while preserving readability. Which means I can get rid of the subsections, and only keep the split to Developer/Sysadmin/Desktop (and rename them as Developer/Server/Workstation, as Peter suggested, to keep it in line with Fedora editions). That would reduce the number of pages from about 20 or so to 4 (these 3, plus the intro section).[1]

This is actually relevant to the script’s limitations. One of the reasons I avoided using the script in F39 was that I really don’t want to use whatever is in the Change pages, and this becomes incredibly obvious in cases where there’s only one relnote on a page, it just looks horrible. Having more content condensed on a single page would alleviate this problem, which means we could more reasonably use a few of the fields on the Wiki, maybe have the script mark them as autogenerated and upon manual review a writer would remove the mark.

To do this, we’d need a slight change in the Change process - because we still don’t have a way to determine where the script should put each change, and if it can’t do that, then I can just as easily copy-paste descriptions from the Wiki myself and the script doesn’t really help me. So how about we create a set of Wiki categories for Release Notes sections, and require every Change page to belong to at least one, and have the script use those to determine where they go? We wouldn’t even need to create new categories for each release, since each Change is already in a release-specific category (e.g. ChangeAcceptedF39). @mattdm What do you think?

Obviously, having Change owner write their own proper release notes would be much nicer, but let’s be realistic :slight_smile: This proposal doesn’t solve the problem with actually writing good release notes, but the descriptions from the WIki could at least be used as placeholders and be better than nothing, especially if they’re marked as autogenerated.


  1. Or a bit more, because a page for distribution-wide changes (new editions, etc.) would probably be useful too, and maybe one for IoT and Silverblue etc. - but definitely fewer than now. ↩︎

2 Likes

Would you like to teach about how to contribute to release note on writing workshop? I want to have a go with it, but end to end process is hard to grasp. We got a short on-boarding session for 30 min as well as 1 hour session, alternating each month.

I’m looking for next topics that we need to prioritize.

Did I already answer here? Whatever, I can do that. Wouldn’t it be better to do that when we actually need Release Notes writing? E.G. When we have a F40 Beta or RC?

Thanks for your heads-up.

Whatever new topics, we need to reshuffle agenda for writing workshops in 2024. We can have multi series release note writing from theory/background (Jan or Feb), to F40 beta (Mar or Apr).

p.s.) what is RC?

Release candidate.

Maybe we can ask the engineering teams what they need in order to consistently write documentation for a release? I strongly suspect that the problem is that contributors have limited time and submitting documentation for release notes is not a requirement, but maybe there is a problem that the Docs Team can solve.

3 Likes

Which teams do we need to ask? Each release note has maintainer(s) or package owner. Could it be them?

Just for information:

We started with efforts to improve the Release Notes by introducing some kind of auto-generation about a year ago. Unfortunately, I don’t have the link out of my head (such a shortcoming in organization is one of the criticisms of leaving mailing lists). We already had a lengthy discussion with FESCO about Changes of the Change Form and made some decisions. But we were not able to fully implement this due to unfavorable changes in Docs Team / Docs Board.

We now have the results of an initial trial. Let’s create a revised plan on this basis. And then implement it on this basis. This discussion is ongoing, and the next step (after Petr’s report) is an evaluation of the empirical results in relation to the original plan. That’s obviously my part (I wrote the summary of our last (first) plan) and I will do that, but I can’t do everything at the same time. So we need some patience.

Part of the discussion must then also be a better involvement of the community, which the last plan had overlooked. This will then include a workshop to communicate how it works. This includes a podcast and further actions to spread the word and attract contributors.

1 Like

No problem. I’ll take your lead on this. If release note can be a priority for Docs team efforts (including coordination with other working groups), I believe it is worth doing it, timed for the next release or next next :slight_smile:

1 Like

Most changes don’t need more than a sentence or so. And if you compile a lot of sentences together, suddenly you’ve got release notes!

Given the number of separate change proposals that end up being accepted for each release, if every one of those contributed just a single sentence to the release notes, we’d have… well, we’d have a lot more of a Release Notes document than what currently lives at Release Notes :: Fedora Docs

Granted, not every change proposal warrants a Release Notes entry, even a single sentence. Some things are purely internal.

But if every accepted Change Proposal had its Release Notes field automatically imported into the final document, verbatim, we’d be halfway there, and 50% farther than we’ve been for past releases.

We also shouldn’t be afraid to enforce documentation requirements with policy: Change Proposals without Release Notes don’t get accepted unless it’s determined that the change should not appear in the Release Notes. Period. Doesn’t matter who writes the note, but having it is a required part of the process, as much as the Change Proposal itself.

There’s also a chicken-and-egg thing. If people writing Change Proposals see that whatever they put in the Release Notes section is going to appear, verbatim, in the actual Release Notes, they’ll take that field more seriously.

I guarantee it does not look worse than entire EMPTY SECTIONS, in the release notes. We can’t do worse than that, so on the bright side there’s zero pressure.

1 Like

(We should also do away with the predefined subpages under Developers,1 because (a) they’re an unsustainable collection of arbitrarily-chosen technologies that is guaranteed to age poorly unless it’s constantly reconsidered and updated, and (b) we can’t even come up with enough release notes to fill ONE page, we certainly don’t need 9–10 blank ones.)

  1. And in System Administration, come to think of it. Because, again, (a) arbitrary (Who determined that every release is expected to have news on the “Printing and Scanning” front? Or even “Networking”? The F39 notes sure didn’t.) and (b) all of the notes actually present on all of the subpages could comfortably exist as sections of a single page.
2 Likes

Being succinct with release notes is a must in my opinion. Most of the times I just want the high level view of the changes, and can dive into the details of the particular proposal if interested.
I also would like to see Fedora handle it’s cve’s more openly (not that I think anything is being hidden purposefully). I don’t know if there is such a thing already, but I’ve never read it. I would make the doc a one pager if possible and have it succinct, with links to more info for each release note. Something like this could be generated from the CP description I would think, and the link to the change proposal wiki for details. Or am I missing.
As for the release notes themselves I think not including “internal to the project only” release notes that don’t have an affect on user experience should never get a note. Also I would add this document should not be the source of truth for all changes made to the project that land on the particular release, the Change Proposals should be that source of truth.

2 Likes

Agreed. I mean, I hate to disparage the very few Release Notes entries we do have for F39, but take the Vagrant 2.3 notes:

Vagrant 2.3

The vagrant package has been upgraded to version 2.3.4, which provides multiple bug fixes and enhancements. Notable changes include:

  • Isolate loading incompatible libraries to support end of life (EOL) platforms
  • Detect network type when not provided
  • Add fix for Powershell 7.3.0
  • Support VirtualBox 7.0

The following package dependencies for vagrant were also updated:

  • rubygem-net-ssh
  • rubygem-net-scp
  • rubygem-net-sftp

Due to the new rubygem-net-ssh, the updates for the packages above are built and delivered as one unit.

A full list of changes in Vagrant 2.3.4 is available in the upstream release notes.

That could’ve been,

Vagrant 2.3

The vagrant package has been upgraded to version 2.3.4, which brings automated network type detection, support for PowerShell 7.3. 0 and VirtualBox 7.0, and other improvements. See the upstream release notes for details.

2 Likes