How do the release notes come together?

Project Discussion
1

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
2

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
3

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
4

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
5

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
6

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. ↩︎

1 Like