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).
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 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.