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@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
