Re: F26 Release Notes help needed

[Petr Bokoc <pbokoc@xxxxxxxxxx>]

Hi Simon, please push to f26. Thanks for your help!

Petr

On 06/28/2017 10:55 PM, Simon Clark wrote:

Hello Petr,

If we have commit privileges for the release-notes repository and are happy to write DocBook, should we push to master or to the f26 branch?

Simon

On 22 June 2017 at 14:30, Petr Bokoc <pbokoc@xxxxxxxxxx> wrote:

Correction: Turns out I remembered the registration process wrong. After you register in FAS, log in to pagure once, and then send me your nickname either in a mail (off-list) or on IRC - I have to add you to the "fedora-docs" Pagure group before you're able to assign issues to yourself.

Apologies for the confusion.

Petr

On 06/22/2017 12:58 PM, Petr Bokoc wrote:

Hi everyone, let's revive this a little bit.

We're going to have to produce some release notes for Fedora 26. I've seen a few people on the list in the past mention they'd like to help, and writing these is probably the best way to start with that.

Note: There seems to be some confusion among newcomers: the Docs Project doesn't maintain the Wiki, we take care (well, occasionally...) of docs.fedoraproject.org. The guides published there are currently written in DocBook XML[0], stored in Git repositories on Pagure[1], and published using publican[2]. We have some vague-ish plans to replace most of that with something more modern and accessible to newcomers, since docbook really isn't user friendly, but that's not going to happen for F26, so for this release we'll have to stick with our current tools.

Luckily, Release Notes in particular can be done in a way that avoids DocBook, Git, and Publican altogether; they're short bits of text I or someone else with experience can mark up and commit for you - you just need find the right information and write them.

The only thing you will need is a Pagure account - which is actually your FAS account. If you don't have one yet, make one[3], make sure to sign the CLA (Contributor License Agreement), log in to FAS, and apply to join the "docs" group; I'll approve you once I see your application. That should give you permissions to comment on Pagure issues, which is where I'd like you to save what you write for release notes unless we agree on some other approach. Also, I'm pretty sure gaining membership in a group will allow you to edit the wiki, if you're interested in that - wheee!

If anyone has any questions, contact me on this mail or in #fedora-docs on IRC; my time zone is CEST (UTC+2) and I'm online mostly during afternoons on workdays.

===HOW DO I ACTUALLY CONTRIBUTE?===

Lately our main focus was covering Accepted Changes in our release notes, since that's an easy and expansive source of information about changes in each release.

I took the liberty of opening an Issue on Pagure for every change; you can see them here: https://pagure.io/release-notes/issues

Contributors should:

* go through the list and find something to write about that isn't assigned to anyone yet (the rightmost column), open the issue and the link to Wiki inside it

* on the wiki page, you'll find three important pieces of info: 1) a tracker bug in Bugzilla, 2) change owner(s) and 3) a short, hopefully coherent description of the change.

  1) the tracker bug is somewhat useful when trying to determine if the change actually made it into the release. Don't count on it really being there, in theory changes that are postponed or canceled should be deleted from the wiki or at least marked somehow, but they often aren't. Therefore, check the bug's status: if it's on ON_QA, VERIFIED, RELEASE_PENDING or CLOSED-CURRENTRELEASE, it's safe to assume it did make it in. If it has a status like NEW, ASSIGNED, or MODIFIED, contact the owner before you start writing and ask them if the change made it to F26. If it didn't, we shouldn't be writing about it.

  2) the change owners are people you should contact a) to check if the change still applies if required (see above), and b) when you write a draft release note so they can check it for technical accuracy.

  3) the description should give you some information so you can get started on your draft.

* once you have something you believe to be publishable, go back to the Issue on pagure and save your text as a comment there.

Some additional notes:

* the current issue list (or the changeset wiki page) is by no means exhaustive. You're very welcome to add more release notes for things like changes in widely used components from kernel to firefox to freeciv. Just make sure you're writing about a component version that will be available in Fedora 26 upon release, not a previous version, *not the latest upstream version*. It's common for Fedora to come out with something like Firefox X, but on its website you can already download version X+1 at the same time. We're writing this about Fedora, so keep that in mind. The previous sentence also means that we shouldn't be covering any third-party repos, proprietary drivers, etc. - Fedora only.

* there often are upstream release notes that are much more exhaustive than what we would write, so use them. I'm talking about changes like "upgrade Boost to 1.63" - Boost version 1.63 already has its own release notes, and this change just means Fedora is using that version. In that case, you can just write as much, maybe provide a short list of the most important changes, and then link to Boost's website for the full version, like we usually do[4].

* the current release date is July 11, so please, make sure you're done two days before so I have time to convert everything. If you can't make it, please send me an e-mail and drop (unassign) any issues you can't do in time. There's no shame in backing out, we all have other things to do, but please make sure someone can still pick it up.

===BUT PETR, HOW ARE WE GOING TO PUBLISH? WE STILL NEED THAT ANCIENT PUBLICAN VERSION THAT ONLY RUNS ON A FEDORA RELEASE THAT CAN'T PUSH TO PAGURE!===

Yeah, but we should be able to publish by building the website in the VM like we used to until now, and then mounting the VM's storage on a more modern system that can push and doing the last step that way.

Good luck everyone, and again, ping or e-mail me if you have any questions.

Petr

---
[0] http://tdg.docbook.org/tdg/4.5/docbook.html
[1] https://pagure.io/group/fedora-docs
[2] https://jfearn.fedorapeople.org/en-US/Publican/
[3] https://admin.fedoraproject.org/accounts/
[4] https://docs.fedoraproject.org/en-US/Fedora/25/html/Release_Notes/sect-Release_Notes-Changes_for_Developers.html#sect-Development
_______________________________________________
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@lists.fedoraproject.org

--
Petr Bokoc (irc: pbokoc)
Technical Writer
Customer 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@lists.fedoraproject.org

_______________________________________________
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx

-- 
Petr Bokoc (irc: pbokoc)
Technical Writer
Customer 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