How to write release notes

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi,

I got a question earlier about how to start contributing release notes (or "how to make small contributions", which definitely includes release notes). We still urgently need contributions for Fedora 28, so if anyone wants to start now, even if you want to take one or two issues, it's always appreciated.

You can contribute without having to even touch git or any other tools, so go ahead and read on even if you're completely unaware of our process; all you'll need is a Fedora Account System membership so you can comment in pagure.

Start by going here: https://pagure.io/fedora-docs/release-notes/issues?status=Open&assignee=0 This is a list of unassigned issues in the release-notes repo. *Be careful here*, many are for Fedora 29 or not tied to any release - don't worry about those now, just get the ones that start with "F28 Change: ".

Find an issue you like, and assign it to yourself - when you're logged in using your FAS account, there's a button that says "Take" in the right sidebar, so click that.

Next, investigate. Start with the Wiki page linked in the issue description, check any links in that (there should be a link to Bugzilla that might provide additional information), google around, anything. Of course, if there are any comments by the owner in the issue, that's the first (and possibly last) information you'll need. If you're lost, @-mention the owner listed in the issue and ask them what it's about.

Once you gain some understanding of the change you're covering, you can do one of two things with it, depending on how much time and technical knowledge you have:

* If you're strapped for time, or can't use git (or asciibinder, or asciidoc, ...), just write a release note in the comments. Typically this should be a heading (which will almost always be identical to the issue name), and one or two paragraphs describing the change to Fedora's users. See Release Notes for previous releases for an idea what they typically look like, like here: https://docs.fedoraproject.org/f27/release-notes/sysadmin/Security.html In this link, every heading was originally a separate "Issue" in Pagure.

  Once you're done, @-mention the person responsible for the change (listed in the issue description on top), and ask them for a review; we'll give them a few days to respond. If they have any feedback, adjust your release note, if they don't respond, oh well. Once you're done (or the couple of days have passed), @-mention me and I'll mark up your release note and create a PR. I'll also check assigned issues from time to time in case someone forgets.

* If you want to, you can write your note up in ASCIIDoc (check the repo structure and find a place for it), and submit a pull request against branch "f28" of the main repo. See https://pagure.io/fedora-docs/release-notes/pull-request/148 for a good example; note how the creator of the PR also @-mentioned the owner and asked for a review. Once the PR is merged, the issue it was made for is closed.

There's also a boilerplate in each issue that roughly describes the process too. If you have any questions, either reply to the list, or ping pbokoc or bexelbie on #fedora-docs; we're both in UTC+2.

Happy writing!

--
Petr Bokoc (irc: pbokoc)
Technical Writer
Engineering Content Services

Red Hat Czech, s. r. o.
Purkynova 99
612 45 Brno, Czech Republic
_______________________________________________
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx




[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Red Hat 9]     [Yosemite News]     [KDE Users]

  Powered by Linux