How to write Release Notes: Fedora 39 edition

Hi everyone, this post is intended to serve as a quick guide to contributing to Fedora Release Notes.

Current status
We’re currently looking for contributions for Fedora 39. The current release date is October 17, 2023. See the schedule for possible updates.

The list of open issues is on pagure; relevant issues start with “F39”.

Use branch f39 in the repo to submit your PRs.

How to contribute

  1. Pick one or more issues in the list linked above.

  2. Open each issue you picked, and click the Take button on the right to claim it. (If you claim an issue but later find out you don’t have time to write about it, remove yourself from the issue ASAP so others can see it’s free and take it!)

  3. Find information about the issue. A lot of them have plenty of info in them already, especially in the Wiki link; if you need more, find out who’s responsible for the change (also listed on the Wiki page linked in the issue), and @-mention them in the issue comments or talk to them on IRC or via mail. Keep in mind that it’s always better if you try to do research before you ask questions. Note that you might not always be able to reach the owner in a reasonable time frame; in that case just do your best, if something ends up being wrong, we can always update it later.

  4. Write a release note about the issue. If you’re not sure what exactly a release note looks like, check out some of the previous releases for inspiration. We don’t want any long, overly technical texts, the release notes are generally meant to highlight changes, not to tell people how to use something.

  5. Now the workflow diverges based on your permissions and technical skills:

    5.a If you know how to use git and asciidoc, write up the release note and send a pull request against the main repo, branch f39. Your contributions should go into one of the files in modules/release-notes/pages/, which one exactly depends on the contents
    of the change you’re documenting. Use the script in the repository root to preview your changes locally; see the docs for specific instructions. If you can’t see the section where you added your contributions at all, check that it’s included in modules/release-notes/nav.adoc.

    5.b If the above sounds like gibberish to you, it’s fine: just add a comment with your text into the issue, and someone will mark it up and add it to the final document.

And that’s it! Repeat as much as you want with other issues.

See also our contributor docs for some additional info and tips; especially the “Git for docs writers” section if you’re not familiar with the system.

If you have any questions, go ahead and ask on this forum, or in Fedora Docs on Matrix.


Shouldn’t we put this on our team docs pages as part of the contributors guide?

Updated for F39.

As for moving this to the Docs Contributor’s Guide - well, there is a section on relnotes, but it’s easier to keep up to date here. I’ll have to think about it.

I’m not a member of the Docs team, but I think there were some changes to the release notes processing (at least, some envisaged changes). The change owners are assumed to prepare a release note as the part of the change process. And the aim of the Docs team is to compose/create the release notes automatically from the change page(s). But as I said, I don’t know if this processing change of release notes has been implemented (worked out) yet.

Don’t understand me wrong, I’m not saying this contribution process is not needed anymore. :wink: