I'm opposed to this for a number of reasons, in no particular order:

1. It requires automated parsing of what is essentially free-form text. This is fragile, as the scripts that currently parse those pages can attest.
2. Requiring the change owners to categorize the release notes entry requires them to make a decision that seems better suited for the Docs team
3. Enforcement seems difficult. If a package update has landed but the release notes entry doesn't exist, do we force the update out (i.e. by bumping the epoch). Enforcement of the existing mandatory fields is already challenging, but adding post-approval enforcement makes the problem worse.
4. The proposal does not indicate if the current process of opening issues for release notes should continue.
5. The proposal does not indicate how Changes that are deferred after branch (which is a very common occurrence) will be handled.

Parsing the existing Release Notes field in the Change proposals into a file which the docs team sorts would accomplish some of the improvements without introducing additional process challenges.

(1) It requires automated parsing of what is essentially free-form text. This is fragile, as the scripts that currently parse those pages can attest.

It is fragile, indeed, and may result in some strangely formatted passages in the release notes now and then.

The alternative to automated processing and accepting all its problems, is to settle for decidedly incomplete release notes in the long run. We should then honestly rename them to "Some randomly compiled release notes". We should seriously give up pretending something that we cannot bring about.

(2) Requiring the change owners to categorize the release notes entry requires them to make a decision that seems better suited for the Docs team

It is necessary to reduce the workload for the docs team so that it can be managed with the available resources.

The alternative to an additional category is to use already existing distinctions, such as grouping only by system-wide and other changes.

Another alternative is to classify only broadly for non-system-wide changes: (a) Generic, (b) Desktop (b1: all, b2: Workstation, b3: Silverblue, b4: Kinoite, b5: spins, b6: labs), (c) Server (c1: all, c2: Server, c3: IoT, c4: CoreOS). That should be reliably feasible for everyone.

(3) Enforcement seems difficult. If a package update has landed but the release notes entry doesn't exist, do we force the update out (i.e. by bumping the epoch). Enforcement of the existing mandatory fields is already challenging, but adding post-approval enforcement makes the problem worse.

This is a question of how seriously we take our documentation, how much we care about attracting new users (and new potential contributors), and how much effort we are able to spend. Currently, based on various discussions, it seems to me that documentation is our weakest point, making new users decide against Fedora. So it may be worth putting some effort into documentation improvement.

An alternative would be to make it as "mandatory" in the Change Proposal form as various other items, but waive specific enforcement for the time being. Perhaps this alone would bring an improvement. We may evaluate it after about 3-4 releases.

(4) The proposal does not indicate if the current process of opening issues for release notes should continue.

We didn't specifically discuss that. It depends on the details of generating the release notes file and needs to be decided upon later. But basically, this proposal is to replace the current process.

(5) The proposal does not indicate how Changes that are deferred after branch (which is a very common occurrence) will be handled.

This depends on implementation details. One option (we would probably use anyway) is to create the release notes of each change as "partial" (CMS-technically) and compose the final document only of partials of the finally included changes. This could be done together with RC 1 or even between the go decision and the release date - without compromising the quality of the document due to its late creation. We may also decide to create the release notes dynamically on a regular basis, e.g. every night or even every hour.

I like the idea of using Change pages more. The processes and the Change documents are very well established in the community, people generally know about them and use the information they contain, and because of this Change Owners often put a lot of effort into those texts. So those Change pages are an asset and we should make more use of them.

But I also think that there's no hope that Change page texts can be used to form a coherent document without any editing. People use different styles, some people write very tersely, some people are not too good at English grammar, etc.

Also, many Change pages don't have Release Notes, and asking people to fill them in would be an additional burden.

I'd propose the following workflow:
- for each page, if Release Notes is filled-in, take that
- otherwise, take the Summary
- if the resulting text is "not good enough", anyone (members of the docs team, Change owners, other contributors) can fill-in or adjust the Release Notes text without confirmation from the Change owners.
- also, if there's something in the Change page structure that confuses automatic extraction of release notes, anyone (as in previous point) can adjust the structure without confirmation.
- the Release Documentation would be recreated regularly until the relaese as described by @pboy above.

In effect, the Change pages becomes more "community-owned", albeit in a limited scope. We should get "good enough" text for almost all Changes. And if something does not look right, volunteers could fix it without too much ado. I hope that the aspect of Release Notes looking 90% OK, but with some clear shortcomings, will gamify the process and entice volunteers to fix the remaining 10% of Change Pages ;)

This will be discussed during FESCo meeting today at 17:00 UTC. @pboy (and anyone else interested) are invited!

The docs team's proposal does not aim to create release notes in a fully automated process. This cannot work, indeed.

The aim is above all to limit the workload to that of an editor / reader in the publishing industry, who does the final post-processing just before the publication. This means:

• The text needs to be complete
• The text needs to be in the basically correct structure and arrangement/sorting

In the final post-processing formatting issues, clumsy phrasing (as some of mine here), etc. get fixed. During the beta and before the final post-processing, every community member can contribute, of course (and should).

And we want to make sure that we have a complete set of release notes, if maybe only as a title at the very worst.

So, we are fine with @zbyszek's workflow, probably slightly clarified/modified (the first 2 dashes):

• As with the Change set, we take the title ("= TEXT =") and the Summary (leaving off owners and tracking), and add release notes if exists.

• We add to the release notes description field: do not repeat the summary but add additional information for end users if appropriate

• We either sort by "System-Wide Changes" and "Self-Contained Changes" if we don't want to add another categorization or otherwise sort along the additional categories.

This sounds reasonable. I proposed using Release Notes OR Summary because based on the pages I looked at (admittedly a small sample), Release Notes were clearly meant to repeat what the Summary contained in a more end-user-accessible form. But if you think combining both will lead to a better result, that's fine to start with that. I'm sure that the process will get some tweaks based on the initial experience… We don't need to get it perfect the first time.

What about the categorization that was part of the initial proposal? I guess we could add that. IIUC, we don't have a way to implement a graphical drop-down menu, but we could provide an editable list in the template, like we do for System-wide/Self-contained and tracker status. This will be an additional bit of work, but not that much. People have to edit the template anyway.

The summaries I skimmed were not that technical. So I think it is informative for everybody. And the release notes can be focused on topics the end user has to be aware of. May be special update procedures, or additional functions, something like that. And if there is no additional information, it may be skipped (but not the categorization).

And regarding categorization, I think a list to select from would be perfect here.

This was discussed during today's meeting:
* ACTION: pboy to provide a list of categories (zbyszek, 18:08:45)
* ACTION: fesco folks: read the proposal and vote in the ticket
(zbyszek, 18:08:59)

ACTION: pboy to provide a list of categories (zbyszek, 18:08:45)

Alternative 1 - relatively fine-grained, but maybe difficult to manage in the Change Proposal form

01. All systems: Security
02. All systems: Installation
03. All systems: Infrastructure (Network, Storage, ...)
04. All systems: Applications
05. All systems: Development
00. All systems: further changes 

10. Desktop: all / more than one
11. Desktop: Workstation
12. Desktop: Workstation Spin (all spins)
13. Desktop: Silverblue / Kinoite

20. Server: all / more than one
21. Server: Server Edition
22. Server: Cloud (Edition)
23. Server: CoreOS (Edition)
24. Server: IoT Edition

Alternative 2 - compact

01. All systems: Security
02. All systems: Installation
00. All systems: further changes

10. Desktop: all / more than one
11. Desktop: Workstation & Spins
13. Desktop: Silverblue / Kinoite

20. Server: all / more than one
21. Server: FHS file based (updatable system)
22. Server: OS-tree based (immutable system)

And of course any combination, e.g.

• All systems: compact with addition of development
• Desktop: fine-grained version
• Server: compact version

And of course, in the final post-processing we may combine categories which were picked too low. But it is probably too much an effort to differentiate ex post into more categories.

I'm wondering how best to put this in the template. @bcotton, would you so nice and stuff it in there somewhere, pretty please?

Do you want me to come up with the names or should I wait for them to be bikeshedded?. They'd need to be something like ReleaseNotes_All_Security or similar. That way they could be listed in the template as

<!-- [[Category:ReleaseNotes_Choice1]] -->
<!-- [[Category:ReleaseNotes_Choice2]] -->
...

And actually, it would be good to have a definitive reference (with descriptions/guidance) on the Docs site to point Change owners to before I ask them to start using it.

it would be good to have a definitive reference

That's a good idea. I'll add a section or subpage to the Contribute-to-Release-Notes guide as soon as we have a decision.

They'd need to be something like ReleaseNotes_All_Security or similar...

Could it also be an option to let the change Owner enter only the category number? And to name the categories compactly in table form (and with link to the reference page)?

Hmm, do we have to do this using Categories? We could have just a text field that would be processed by the script to gather notes. I assume the script will gather all the Change pages, and it won't be using the wiki Category pages, but instead look at the page text directly, so using the Category system doesn't buy us much.

Something like this:

Applies to:
<!-- Remove all lines below __except__ the category or categories where this change
     should be shown in Fedora Release Notes.
     If leaving more than one, add commas to separate the items. -->
01. All systems: Security
02. All systems: Installation
03. All systems: Infrastructure (Network, Storage, ...)
04. All systems: Applications
05. All systems: Development
00. All systems: further changes 
10. Desktop: all / more than one
11. Desktop: Workstation
12. Desktop: Workstation Spin (all spins)
13. Desktop: Silverblue / Kinoite
20. Server: all / more than one
21. Server: Server Edition
22. Server: Cloud (Edition)
23. Server: CoreOS (Edition)
24. Server: IoT Edition

(Removing is faster than uncommeting, because you can it's just a few keystrokes in the editor.
But we could do the uncommenting instead, like with other fields.)

Could it also be an option to let the change Owner enter only the category number? And to name the categories compactly in table form (and with link to the reference page)?

It could, but that increases the burden on the change owners, and the more you increase the burden the less compliance you'll have.

Hmm, do we have to do this using Categories? We could have just a text field that would be processed by the script to gather notes. I assume the script will gather all the Change pages, and it won't be using the wiki Category pages, but instead look at the page text directly, so using the Category system doesn't buy us much.

It doesn't have to be done with Categories. The reason I suggested it was two-fold.

1. It decreases the complexity of parsing the pages. What happens when people mis-edit the string? That happens a lot already with other fields (in particular, the contingency plans) so if people mis-order the string and the actual text, you have to account for that. Also if they accidentally delete the : or the space or... I'll grant that this is also a possibility with using Categories, but they're a little more distinct. In practice, I see a lot fewer errors with [[Category]] elements than with text. It also makes it easier to include a note in multiple categories, which might be desired in certain cases.
2. It opens up possibilities for using the field in other ways. For example, listing all Changes from any release for a given category of release notes. This lets someone visit the wiki and see a (unsorted) list of changes for, e.g. IoT since we started using this mechanism. Is that useful? Maybe not. There may be other uses that don't occur to me at the moment.

Ultimately, I'll go with whatever the Docs team wants to do. But this is my recommendation.

@pboy, @bcotton can we make some decision here and close this?

W'll discuss this today (Wednesday) on Docs meeting .

After discussing the alternatives, Docs team would prefer / recommend:

• using wiki categorization as Ben recommends
• using a combination of fine-grained categories for system-wide changes (6) and compact categories for others (Desktop 3, Servers 3).

• using a combination of fine-grained categories for system-wide changes (6) and compact categories for others (Desktop 3, Servers 3).

If you can confirm the categories, I'll update the template and the Changes documentation. Please open an issue in the pgm_docs repo when you have the list or the appropriate docs to link to and I'll get started on that.

FESCo members: we need to vote to approve this formally.

+1

After a week: APPROVED (+1, 0, 0)

Announced.